yours, Marcus

there is NO rule stipulating that PEAR documentation has to be written in DocBook XML. If people e.g. want to write documentation for a package in a Wiki, a link to this Wiki will be added to the PEAR manual.

LaTex _does_ have WYSIWYG editors out there, which makes me wonder if it might be a better place to start. There do seem to be ways to convert LaTex to docbook e.g. TeX4ht – looks like alot of work is needed to configure it but once done, could make the config available via the PEAR website.

If I would place any responsibility I would surely place it with the users, especially those who have received answers from the original author when they asked questions.

There can’t really be a law that if you publish code to the public you have to also write proper documentation for it ;)

Of course it would be good if there is documentation and yes, the original author is in a good position to write it because of the intimate knowledge of the code. However, my opinion is that code without documentation is better than no code at all.

If just one single person finds the code, figures out how to use it, and use it in some way. It’s useful to publish the code. If there were 50 persons who found the code but couldn’t figure out how to use it due to the lack of documentation they are not worse off compared to if the code wouldn’t have been published at all.

Documentation should be written by those who can. Those include the original author as well as anyone else who has learned something about a piece of code.

That skips the question of whose responsibility is. I maintain that it is the responsibility of the author. If the wuthar can get other people to do it for him wonderful; if those people then do not produce docs, the author failed to fulfill his responsibility.

The author writes a program, the author decides the world should see the program, the author publishes the program. Then, when a user asks how to use the program, the author says “figure it out yourself” (or worse). If the author receives multiple questions about the same topic but cannot be bothered to publish the answers as documentation, somehow it is because the user did not “get off his ass”. This does not scan. The one person in the best position to write useful documentation about the program is the author; nobody else “feels inclined to contribute” because they’re spending all their time trying to figure out the program — because there is no documentation.

I’m certainly not immune from the laziness that keeps things from being documented, but for my projects I have found that using XHTML docs makes it 1) extremely easy for me to update docs, and 2) makes it extremely easy for others to contribute docs. (It’s basically the XHTML+XSLT solution that Binarycloud uses.) With XSLT and other 3rd party tools like htmldoc, it’s possible (even easy) to create other formats (e.g. PDF).

I agree that it is the responsibility of the original developer, but I also think it makes sense to lower the cost of entry for writing documentation.

Thanks for the good YaWiki buzz. :-)

You wrote that you don’t think it’s the original author’s responsibility to actually write the documentation. Other than a formal documentation person or team, neither of which generally exist in open-source userland public PHP projects, whose responsibility would you say it is?