Re: Is your package really documented? The truth

<gurugeek@php.net> wrote : > Hello Everyone, > After reviewing the previous topic, I prepared (manually :(( ) the list > of the PEAR Documentation status as it is today, you can see it at > > http://pear.gurugeek.org/ > > you can also modify the listing if something is not accurate, or make > your pledge to documented the package by changing the status to > "$progress " > and possibly the expected date. > > The list is not completely accurate, aka if you have some external > documentation it is still not documented in the PEAR manual and the > basic documentation with > link should be part of the manual. > > We have 139 not documented packages at the moment (including alpha and > beta releases) I knew the figure was high but here, I am pleasantly surprised ! > Possible solutions: > > a) learn DocBook format and validation, use PHPDocumentor to prepare > your docs and commit to peardoc > > b) Prepare some basic docbook documentation (see > http://pear.gurugeek.org/ for an explanation and some examples) > which links to your website or better a Wiki where you have available > both the API Documentation and some implementation examples. > > I am willing to do the PEAR Manual/Docbook linking and basic > documentation on demand. > > Looking forward your suggestions and comments, None of your proposed solutions will actually solve anything. You are standing in front of an alarming situation and you keep on proposing the same old things as before. You keep on thinking the problem is that people don't know how to use docbook. Even a monkey would know how to write docbook. I think it is time to realize that the problem is not the format but the interface. Use whatever you want to store the data, whether it is docbook or reSt, who cares, but provide an interface that works, that's easy to use, that allows WYSIWYG like editing and where you don't have to wait a whole week to see you made something wrong. And BTW if PEAR wants to continue to use Docbook, it should use at least a standard version, not an old custom incompatible one. Bertrand Mansion Mamasam