It is a USDP-distilled for eXtreme programming, using markdown text in a single file. If you want something practical and undemanding, but based on good process, this may be one starting point:

http://www.hxa7241.org/articles/content/usdp-distilled-doc_hxa7241_2005.html (1600 words / 10 min read)

Instead have been looking at phpDoctor which doesn’t do everything phpDocumentor does but the code base is “lighter”, and getting a prototype working is easier. But of course this doesn’t have to limited to PHP - Dokuwiki pages are “just text” stored in files.

Currently stuck on a good way to re-generate wiki pages after the first version, where users may have added comments. Dokuwiki needs some more command line tools as well, for updating pages via it’s API - made a start which Andi accepted here. It might also be worth having some syntax plugins specifically for API documentation - tags like <class/> and <method/>.

There’s also a bunch of issues like how to flag comments as potentially outdated, if the class or method they are referring to has changed since the comment was made. Probably the easiest way to go here is to push these kind of problems onto the users, at least to start with.

Anyway - never enough time.

As you mention Dokuwiki, there’s been some discussion along that lines, specific to PHP and Dokuwiki, here;

http://wiki.splitbrain.org/wiki:discussion:integrationwithapidoctool

Preach the Word, my brothers. I have had the hardest time getting some other developers to believe that lowering barriers to entry on documentation is the number-one way to increase both the quantity and quality of documentation. One rant in particular sums up my feelings when I say that wikis are great for documentation.

IMO, what’s needed is something like Eric Meyer’s S5 (but for narative doc) or a slightly specialized wiki or something.

What’s had the most impact on my tendency to write doc has unquestinably been Markdown and Restructured Text. When you lower the barrier to writing good doc that far it becomes hard to make excuses for not writing doc or for pushing it off.

Some tooling around an insanely simple text format that offered some of the features of docbook (let’s say the top 20% of docbook features like TOCs, multi and single page output, figures, index of citations, etc..) would probably go a long way.

Self-documenting code is nice, but that still doesn’t get to explaining the essence of a system. Martin Fowler has commented in the past on generated UML documentation in particular. My own CTO recenty captured the essence of the problem here.

I love the idea of what some of us in work call a ‘narrative’. It’s purpose is to capture in a few pages or diagrams, the essence of what’s truly important in a software system. When I was an industrial designer we had technical drawings called general arrangements (GAs) that provided that information. In real architecture, this is essentially what architects drawings and building models provide. The XP/Agile folks notion for this I think is the system metaphor, which tries to cut the essence to a single metaphor or a few sentences - the consensus there seems to be it’s very hard to do well.

Any sucessful system is subject to ongoing change. That means you have to make an economic choice during change; do you put aside time and money for keeping the documentation in sync or do you sink that time and money into executable software? In any case, being able to capture a system essence is a real art form in a place where you would love it to be mechanizable, and not art. I suspect trying to solve it through generated documents alone is Hard AI by stealth.

“Yes, right tool for the right job, but for me ’satisfactory’ includes documentation. As a stakeholder I would be keen to know that the code is maintanable by someone else.”

I couldn’t agree with you more. But I’m questioning the ‘one size fits all’ attitude. Most of the applications that are going to be written in RoR will be throwaway products. Does it make any sense to bother dressing them up?

For example, not that long ago I got contracted to write up an analysis report for a company exploring certain options. They consumed my report in about one hour, and put it gently to rest. They will never ever revisit it.

Now, would it make any sense for them to insist that I document that report? That I put my thought process on paper, all the meta-information surrounding my efforts in writing that report? Why bother, if it’s been consumed and disposed off? Who’s going to be maintaining the already defunct report?

Same thing will start happening with business apps that are going to be rapidly built in RoR. I call it ‘the Cleenex syndrome’.