On Fri, 29 Aug 2008, Chris Frey wrote:
On Fri, Aug 29, 2008 at 02:00:58PM +0200, Klaas Freitag wrote:
But to write good user documentation about the BS it requires more than just having it in the source repo. Such a documentation needs professional editing, a good concept, ongoing proofreading etc. That is doable, but not from developers who work on the code. They (we) simply can not do that, not only because we're usually bad writer, but because we simply do not see where documentation is needed. As the developer of a part of the system, all seems so obvious that one thinks it is not neccessary to document it decently. As features sum up, things get messy.
I hesitate to chime in here, since this is a controversial topic, but I so strongly disagree with the above, that I must respond.
I do as well, but I really think the stuff below really needs to be done.
I'm not saying this to tell people what to do with their time, or to tell Novell what to do with their resources. I just want to point out that this task is relatively straightforward, since the community tells you how to do it, if you're looking.
Any developer good at his job is good at organizing things, and documentation is just one more set of code, but written in English or German instead of C or Python. The table of contents is your main() function.
Anyone who spends much time on the mailing list answering questions, or in the irc channel helping people with spec files, will have the weak areas of the documention pointed out to him. If it is not possible to completely answer a user's question with a URL pointing to a page in the manual, then the manual needs work.
If there are only one or two people doing the bulk of question answering, it will eventually get to the point that it is easier to answer questions once in a manual than multiple times on the mailing list.
New users need:
1) An overview
This has to be high level, birds-eye view. It needs to tell the user what the pieces are, how all the pieces fit together, what things are assumed, and what things the user must supply.
For example, when I started out, I had the hardest time figuring out how to tell the system which file was my spec file. An overview that told me that the server automatically scans for *.spec and *.dsc files after every commit would have helped ease the pain. Instead, it was a patient and helpful irc user who told me.
2) A reference
This is an organized, outlined list of features that are available in the server, the client, any libraries, etc. Every feature is listed, in its proper section, with a description of what it does, why it is needed, how to use it, and an example.
3) A tutorial
This consists of one example, of varying complexity, taking the user's hand and going one step at a time, showing a piece of the spec file, and showing the solution to any problems encountered.
One way to do this would be to look at the commit history of a new, small project committed by a new user, and describe the steps and pitfalls he encountered.
Again, any newbie questions that keep coming up on the mailing list or irc indicate places to improve the tutorial.
4) Examples
Ideally these examples:
- are embedded in the reference - exist as one large example in the tutorial - have a spot in source control for a variety of sample spec files, and listed in an appendix of the documentation
5) One location for _ALL_ of the above
There should be one outline from overview to examples, with links to each section, page, and example.
I think this is OBS's sticky point... some of the above items are already done, but it's just not organized on one page with a comprehensive outline, guiding new users through the maze.
And the great thing is that this doesn't have to happen all at once. And if there is one place for this in source control, people can send patches to it as if it were code.
To get the ball rolling, the following decisions and actions need to be made:
1) What format to write it in
If you want contributions from everyone, it should be something that many people know how to write. Maybe more people know HTML than DocBook? Pick something everyone knows how to write.
2) Who is responsible for adding documentation submitted by users?
Sometimes a user might be willing to write some paragraphs on how to use a feature he just figured out, but won't be willing to write it in the XML manual format you chose. Have them write the docs in a simple email, and have a Document Wrangler paste it into the right section, and format it.
When asking for a user to write a paragraph or two, point them at the outline, and ask them to write section 1.2.3. Sometimes their issue or question may prompt an update to the outline itself.
3) Setup a process where the source control is automatically built
The manual needs to be updated, live on the website, straight from source control. An outline is a great help here, with long lists of sections of features that are not documented yet, but at least listed. I'm sure there are developers would could make a list of features in various sections of the system, and this can be organized into an outline. As users hit those roadblocks, each section is filled in.
Harness the newbie questions, and with a little thought and planning, they will guide you to creating excellent documentation.
More information on documentation can be found here:
http://producingoss.com/en/getting-started.html#documentation
Even look at the table of contents of that book:
http://producingoss.com/en/index.html
OBS needs a table of contents like that, even if the links don't point anywhere yet.
+1
--
Boyd Gerber