Note: This discussion was imported from Loomio. Click here to view the original discussion.
This I think is self explanatory.
How can we change anything if existing code base is an enigma?
Or does it mean we are dumping all or part of the existing code?
I think having some kind of general overview for explaining D*'s working parts would be useful. It’s not so much of an enigma if you can read Javascript/Ruby/SCSS/etc, but I think explaining how the different bits hook together would definitely be helpful.
Hi Sean,
Well, I’m not sure how to take what you mean. Of course I can’t read code, and I don’t need to as a user. But I have heard endless complaints that no one knows what the code does that is there now.
I have no way of verifying that myself, but if there is no documentation on existing code, that is really astounding to me, given that this is a FOSS.
It seems that we need to be disciplined and do a little housecleaning if we want to welcome the work of others to include into the code.
I mean when I am expecting company, I start tidying up. Shouldn’t we do the same?
In my experience most (and especially) FOSS projects have problems with their documentation…
Nothing against a rework of the Intro to D’s codebase doc in the wiki, but documenting every single piece of code is not useful and a waste of time.
A programming paradigm says that if you feel you need to add an comment to your code stop and spend that time instead rewriting the code to be self explanatory. Documentation often gets outdated, is wrong, disrupts the reading flow and is just cruft.
However there’s nothing to say to generate a proper documentation of libraries you create so others don’t have to read your code just to use it. How to modify is pratically never covered in that documentation.
There’s also nothing to say against documenting the federation protocol in more detail, I just won’t do it because I have no fun doing it and fun is my main motivation to work on D*.
I hang out on IRC a lot, so just stop by there or on the ML and I’ll answer your questions on how things work in D*s codebase to my best knowledge.
@Florian: if it’s the standard for FOSS not to document the code, then why have I heard so much grief about no documentation? From what it sounds like the entire movement forward is stymied because of a lack of understanding things like federation. I mean if I just heard it from one source, that’s one thing, but it seems to be a common complaint. Even if it is a common complaint for FOSS, why should we let that happen here?
The more documentation there is, the easier it is for people to pitch in and get involved. Why wouldn’t we want that?
@Jonne: Well I think there are different levels of documentation. What we are speaking of here is Code Documentation. In all the contact I’ve had with coders (which is limited but certainly more than the average user), the ones who are sterling in their abilities practice good documentation of their code.
Why not make that a part of the culture here? Everyone benefits that way, yes?
I mean, OK part of this is about having fun, but is that all that it’s about? I can imagine that in a situation not being able to grok the code because of a lack of documentation is not any fun.
Your offer to speak to anyone on IRC to learn how the code works is very generous. But I wonder, wouldn’t it be easier on your time to document it and then point people to that?
That thread made me loading the diaspora code in my IDE , havent worked on it since … the dark age in the community…
In the process of learning I sometimes find myself loving to write documentation. cu @ IRC
@madamephilo I sincerely like to encourage you to strengthen your believe in the devs to improve and master the code.
I guess there is a team forming on IRC to document existing code?
@groovehunter: there is no reason for me to not believe in the coders. If that were the case I wouldn’t be here!
I am clearly in the minority here, and you have to think that takes a little bit of metal to deal with so many propellers running!
AND I’m missing a Y chromesome…
Simple answer? No. In a conversation I can adjust the level of explanation to the skills of the other party, we can find out things together (you seem to assume I’ve got absolute knowledge about every single piece of code in Diaspora, while I’m just good with reading it and with Google). In arbitrary writings about the codebase I would need to make (wrong) assumptions about the reader. I certainly will create/contribute to an FAQ if the same questions come up again and again.
You can’t compare a FOSS project with contract work, in a FOSS project your chance that you can reach the original author of a piece of code or at least someone understanding it, is by far greater, while in contract work that might not be the case from what I’ve heard.
md, if you count groovehunter as a team yes
@Jonne: Sorry, I did not mean to sound like a there is one single solution. I’m just bringing up something I’ve heard discussed and what might be helpful to speak to those folks (who may be reading this in the near future).
I thought that documentation of code is to let people who use the code what it does and how to modify it. I heard this is missing. Especially in regard to federation. What do I know? If I’m wrong I’m wrong. I’m not afraid to be wrong!
I also do not mean to represent how FOSS should work, either. I’m just thinking out loud and asking questions.
I’m certainly grateful to learn more about it. So, thanks!