Mailinglist Archive: opensuse-buildservice (249 mails)

< Previous Next >
Re: [opensuse-buildservice] Re: BuildService documentation not acceptable
  • From: Boyd Lynn Gerber <gerberb@xxxxxxxxx>
  • Date: Fri, 29 Aug 2008 12:37:13 -0600
  • Message-id: <alpine.LNX.1.10.0808291236120.25425@xxxxxxxxxxxxxxxxx>
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

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:

Even look at the table of contents of that book:

OBS needs a table of contents like that, even if the links don't point
anywhere yet.


Boyd Gerber <gerberb@xxxxxxxxx>
ZENEZ 1042 East Fort Union #135, Midvale Utah 84047
To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-buildservice+help@xxxxxxxxxxxx

< Previous Next >