Re: Re: Livedocs

On Feb 23, 2004, at 11:32 AM, Sergio Carvalho wrote:

Paul M Jones wrote:

I partially disagree with your disagreement. ;-) Certainly docs should accompany code. It is trivial to have PageName.wiki.txt in the docs/ directory for as many pages as you like; Text_Wiki can parse them into (currently) XHTML, (near future) RTF, and (undetermined future) DocBook, PDF, etc as one wishes.

I didn't mean it like that. More like Javadoc or phpdoc type comments right in the source code files. Having separate documentation files in the project tree isn't much better than having them in a separate site.

Completely agreed. Inline comments are absolutely required, and more is better. Verbosity and explanation, as if you are training the person reading it; inline comments are an opportunity to teach.

I don't see the barrier to entry for documentation writing lying in the documentation format. There's a much larger barrier in the understanding of the code. That is why I believe documentation must be the responsability of the developer, not some magic helping hand. Noone likes writing docs, much less other people's docs.

Also completely agreed; I have said before in other threads that documentation is not sexy, it is not high-visibility, it is not fun. It is in many ways more of a task than writing the code to begin with, especially when it's someone else's code.

Your comment, however, sparked another idea. How about having comments in PEAR documentation? User comments are one of the best features of PHP's docs. We should be able to replicate that.

Right on! Should be easy to implement; I did it in a day with DB_Table and one comment class extended from it. (Hey, Daniel Convissor, look at DB_Table! ;-)

Incidentally, this is why I like Wiki (and why I wrote Text_Wiki in the first place). A Wiki makes it very easy to collaborate on documentation, distributing the workload and getting many people ("more eyes == better results") involved interactively and with instant results.

Summing up: I believe this is false for the "core" documentation. These reference docs and core tutorials must be written by the code author.

Hell, *all* docs need to be written by the code author, at least to begin with. On this point I have no argument at all. For the reasons of difficulty mentioned above (not sexy, labor intensive, etc) the writing of docs needs to be made as easy as possible; for me, that means iterative development, instant feedback, easy to get started with only one or two pages, easy doc syntax, and easy collaboration (there are many packages that have two or more "lead" or "developer" roles).

On the other hand, wikis are probably very good for "complementary" documentation: extra explanation of library behaviour, alternative usage and bug workarounds, much like what happens in PHP's interactive docs or Postgresql's interactive docs.

This is exactly the kind of thing I'm getting at. In a sense, all documentation is complementary.

Wikis might work very well for non-reference docs, however. I don't have a strong opinion there.

They're great for annotated examples. -- Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/