Mailinglist Archive: opensuse-doc (14 mails)

< Previous Next >
Re: [opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
  • From: Rajko M <rmatov101@xxxxxxxxxxx>
  • Date: Sat, 30 Sep 2006 10:37:16 -0500
  • Message-id: <451E8F2C.1060509@xxxxxxxxxxx>
jdd wrote:
> Alexey Eremenko a ├ęcrit :
>
>> To Novell: please allow the community to write docs, that will be
>> included in the distro for offline use (in RPM package, HTML format).

That would be one solution too. Included rpm for HowTo is probably
example of the way you would like to have wiki articles. Take Mediawiki
software output, strip it to the bare minimum, and put in packages.

> as a very long time linudoc contributor, I know quite well the problem,
> but have no simple solution :-(
>
> A good documentation have to be well organised/structured and this is
> simply not the ordinary way of thinking of most people.

Right.
The problem is that current core team are all (or majority) software
developers (programmers). They know what software will do (most of the
time), and for them is hard to imagine how far is few notes that one get
with --help option from usable instructions how to use software.

> Wikipedia IS a very good information source, but not so well organised
> (and can't be better, probably).

I'm afraid that everybody is expecting too much from wiki self
organizing and healing. It is fine for Wikipedia where you don't have
demand for articles (descriptions, instructions) to be in sync with
anything.

With openSUSE wiki that doesn't work as article about program can't
follow 2 years after program is written. It has to be published in the
same time as software, and updated every time developer changes program.

> SuSE manuals used to be very good, thanks to a very good writing team
> (and probably very expensive too).

For me, that was one of the reasons to stay with SUSE so long.
I can remember the style was excellent for the beginner and advanced
user as well.

> The goal should be to have a much bigger (with tranlations)
> documentation with nearly the same money. I do not have a solution. CVS
> or SVN are of course a good step forward.

The SVN is good step if you have tools and documentation how to use them.
Step by step explanation how to check out, how to submit changes, what
tools to use to edit. Documentation about this tools used in specific
SUSE environment. Yes, documentation about how to contribute
documentation trough SVN and other means would be super.

> writing and translating doc is a very hard work, and even more as a
> voluntary work - I myself took some vacation from suse documentation for
> a month now, exausted by 6 month of continuous work.

I can see that :-D

> the truth is that documentation should be written 3 month ahead of the
> final product (for translating and printing delays) and this is quite
> impossible if we always wan to freeze the distro at the last minute
>
> jdd
>

That will keep happening as long as programmers will think that the job
is done when they are done.

The plain truth that takes in account only physical activity (not
thinking how to write something) is that program source code is
condensed explanation what program will do, so to write documentation
one needs more time than program writer.

How much more?
I would say few times more just to explain program structure, input and
output data structure of functions, what are limitations of used
algorithms (like where it is optimal to use), examples of usage.

For occasional contributors, document writers, we would need templates
or even forms easy to fill in. This way there will be mentioned all that
is necessary to know about program.

--
Regards,
Rajko.
Visit http://en.opensuse.org
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
List Navigation