Note: This discussion was imported from Loomio. Click here to view the original discussion.
There seem to be differences in people’s minds about documentation.
I suggest the term “documentation” possess a broad scope, so that it includes Code, Tutorials, Getting Help, Installation and so on.
It seems that people are using the term in this forum to only mean documentation of code (I presume stored at github).
I propose we broaden this definition, otherwise what do you call documents that help community members who do not code? or who are not installing pods?
This means we would have different branches of documentation: Code Documentation, Federation Documentation, Getting Help Documentation, Tutorial Documentation, etc.
Is this problematic? I hope not. 
We might start with noting the existing in an outline structure. The wiki holds 4 to 5 main branches, usually they’re called install / admin / developing / using
Sometimes it helps to distinguish between polarities
- often changing -vs.- quite static
- can be written almost anybody -vs- needs experts
My usage of the term counts all in. As you asked for it @madame
Yeah, documentation is just “explaining stuff to people”. Not sure where you got that feeling
@Jonne: Well the way I’m reading some of the discussions here, it seems to only be concerning documents for coders. And housing documentation for the more technically savvy will not be friendly for non-technical members, for whom I am advocating here.
Also I think it is quite common in a group such as ours that we discuss the definition of terms. Often, huge problems can be averted if we just knew that we had different understandings for a word. This is confounded further for being from different cultures and speaking different languages. So I’m just attempting to be sensitive to that!
An ounce of prevention is better than a pound of cure, yes?
MD, I agree with you. I second the broad definition. Problematic? Not at all. I think you have noticed that most people here doing the evaluation of Loomio are developers, some developers do not care about documentation at all, some do write some documentation of their own code (if you are lucky), very few bother with other documentation. Maybe I am being a little hard, but it is not far from the truth
@altruism: If what you say is true, then it seems to me that we should be discussing how to document existing code. How can we move forward if there is no documentation of the existing code?
Or does it mean that we trash the alpha and start all over because no one wants to spend the time documenting code???
That is crazy!!!
MD, I am not the right person to say how well the Diaspora code is documented. I was talking in general.
“The code itself is the documentation” is a saying. It documents what the CPU does
For me it’s twofold. I code without documenting a lot. But if someone ask me I come into the mood and love documenting and structuring info.
MD, I just wanna be clear. Documentation of code is something like this (2 lines of comments, 1 line of code):
this is a ruby program
it will say hello to the world
puts ‘Hello world’
the code itself is not so bad that you wouldn’t know what it does by looking at it, if you ever worked with rails before (and even if you haven’t you get the idea pretty quickly - I speak from personal experience).
But from a ‘best-practice’ standpoint, it’s true that the code is seriously lacking comments (= inside the source files) and documentation (= some place else, wiki perhaps, not limited to code-related stuff).
But to be honest, we’re just another Rails project, and we simply can’t afford to re-do all the documentation that is already there for Ruby on Rails (maybe one day, when we have more project members that I can count). Rails is a framework aiming to be dead-simple and it’s doing a pretty good job in many other aspects, too. All Diaspora* does, from a technical standpoint, is to require a bunch of Ruby Gems, connect the dots the way it is dictated by Rails and shuffle around some data inside a database, all with a nice UI.
Thank you Florian, I have not seen one line of the Diaspora source yet, I could not know.
@Florian et al: I do not try to pretend that I know what I’m talking about! But I have heard others frustrated about a lack of documentation. Now if that is comments or that is a offsite repository (like a wiki) explaining what does what I can’t say. But that speaks to the spirit of defining what we mean when we are Talking about documentation.
It doesn’t seem useful to use the word documentation in a way that is too broad when the speaker is talking about comments in the code, for example. See what I mean?
He that was a really exhilarating characterization of how diaspora works @Florian … good laugh! - ten points
I am optimistic as a community governed project we can improve so it counts as a “well documented project”
madame, in software projects the usal documentation is the following: (1) requirements, (2) design, (3) technical and (4) end user.
MD, 1) foundation for what shall b implemented, (2) overview of software components, (3) code, algorithms, interfaces, api:s etc, and (4) for support, sys admins, users.
It seems that 4) is too general. I mean there is support to help a user know what this or that button will do. But what if there is something not related to code? Something that is more cultural based? Like a primer of what to do if you are trolled? Where would that go? It doesn’t seem that that would fit in any of these 4 branchs, you know?
In software there are bugs, no trolls
So are we only talking about code?