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@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org