lesscode … more docs?
By Richard Dyce under Ruby, PHP, First they ignore you.., Rails on 20. September 2005I’ll take it as a given that if you’re reading this then you agree that, for the sake of sanity and productivity, it’s time coders gave up on roll-your-own, and moved over to modern frameworks where one can concentrate on business logic rather than request parsing (and get all those AJAX goodies for free ;-) ).
I’ve been looking on with interest for the last year and a bit, and as I’ve watched the pioneers blaze their XP, RoR, lesscode trail across the web-firmament, I’ve begun to suspect that I must have missed something. Yes, it’s powerful stuff, and yes it isn’t all smoke and mirrors - there really is “gold in them thar hills…” - but, and for me it’s a big but, we seem to be missing the big picture. Where are the map makers? Where’s the documentation for the second (or third) wave?
Self-documenting code is all very well, and having a common vocabulary of design patterns helps when discussing solutions to individual problems. But what second-wavers really need (and I include myself here - no, actually, put me down as a third-waver) are more pictures. More exposition. Road maps.
Is there a way to add XD (eXtreme Documentation?) back into the XP mix? Writing elegant code is hard, and people who do it earn the admiration they received. But I would argue that writing good documentation is harder, and that it shouldn’t be left for the second-wavers to do.
People who’ve moved to XP have already gone thorugh the pain barrier of
- write the tests
- then write the code
- (then refactor)
and have proved that in the long run, it means better code, less debugging, in less time. But having proved that that works, might there be some benefit in switching to;
- write the spec
- then write the tests
- then write the code
- (then refactor)
- then write an overview!!!
Might this result in (my h-nought) more easily modfied code, quicker adoption by other coders, greater community support?
I’m genuinely interested in other people’s views on moving documentation down(?) the food-chain, so that it’s non-optional, and as integral to writing new code (and frameworks) as writing good tests. Yes, there are good auto-doc tools and methodologies out there, but that right now they still seem to be seen as secondary to the process by Joe Frontiersman, and they only deal with what’s in the file, not what’s in the coder’s/architect’s head. (There’s the nine diagrams of UML, yes, but who on the bleeding-wrist of open-source technology is actively using/sharing designs via UML?)
Let me know if I’ve missed a trick somewhere.
[A few thoughts for the pot: I believe the that the reason the Open Source model works because it’s based on non-coercive collaboration. But Source Forge is littered with unfinished, half-baked projects because someone didn’t think to check that there wasn’t already a project out there that they could use. (How many PHPUnits does the community really need?) Should there be a ‘requirement’ for documentation before a project gets listed? Perhaps it’s time for ‘ideaforge’, or ‘architectureforge”?]
Paul M. Jones:
I’m a big fan of narrative end-user documentation. API docs are a good reference, but they are incapable of telling a new user what the important parts are, and how alll the pieces are supposed to tie together. For that, you need narration.
The thing is that narrative end-user documentation not hard to produce, technically: a wiki is a great starting point, and often you don’t need much more. My two major projects, Savant and Solar, are both very heavy on docs, for the same reason you note above: a project is not complete until the docs are done. Both of those documentation sets are wiki-based, which makes it easy to add and link pages.
comment at 20. September 2005
Richard Dyce:
Paul - yes, I agree (personal preference: dokuWiki), but that doesn’t make doumentation integral to the process, something that needs to be done on the way to a finished app/site. And I think that’s the trick. Plus, code is code is code, but documentation is yet-another-format. Perhaps we need a documentation microformat? ;-)
comment at 20. September 2005
Jeff Shell:
Zope 3 uses doctest pretty heavily for most unit tests. It’s not quite end-user documentation, and can sometimes be a little frustrating to read, but it is a narrative that also is valid running code showcasing a particular component or method. Many packages might have a text file next to a module that documents how to use what’s in that module. See, for example, the query.txt file in the Hurry library.
doctest is one of the coolest testing models I’ve seen.
comment at 20. September 2005
hxa:
In ‘Extreme Programming Explained’, Kent Beck expresses sympathy with the Unified Software Development Process. That may be surprising to some. But the USDP way of carrying an ‘architecture description’ through distinct phases of inception, elaboration and construction offers a usefully simple and formalised model for documenting (amongst other things).
Such inception and elaboration documents can be as basic as small text files. If one is creating anything but the simplest software, preparational thinking and notemaking is indispensible. By adapting the USDP you can benefit from channelling such work into a well thought-out and pseudo-’standard’ system. One that is XP compatible.
EXtreme Documentation would be the concept for just this sort of slimmed-down USDP documentation. I’ve been starting to do it fairly recently, and it seems good.
comment at 20. September 2005
Danno:
On the last topic, I agree so VERY hard.
In June, I started writing something, in my mind, would have ended up like a Universal Feed Parser in Ruby because I was frustrated that there wasn’t a regular way to access RSS1/RSS2/ATOM in Ruby. I got about a third of the way done working on it on and off before I noticed on redhanded that someone had gotten the job done AND they had released version 1.0 just about the time that I started my project.
comment at 20. September 2005
Grig Gheorghiu:
I wrote a couple of posts on the topic of “Agile Documentation”, i.e. using tests as documentation. I think there’s a need for it and I’m happy to see “real world” projects such as Django doing it. See http://agiletesting.blogspot.com/2005/08/agile-documentation-in-django-project.html for more details.
comment at 20. September 2005
Richard Dyce:
hxa, I’m right with you…
USDP looks great… but highly proprietary. Also the documentation for it seems quite dry, and isn’t going to motivate people to start using it.
[As an aside - anything that requires 8 - count ‘em - books from Addison-Wesley alone to explain how to implement something in the real world is doing something wrong. I can give someone a copy of the O’Reilly ‘Extreme Programming Pocket Guide’, and they can get a handle on it in 112 pages.]
comment at 20. September 2005
alexbunardzic:
There are potentially three things muddling the picture here. If we are to attain some clarity, we need to specify which of these three are we talking about:
Depending on which of the above three are we focused on, the issue of documentation will change.
If #1, I agree that proper documentation is a must. APIs must be fully documented and supported. But, most of the developers worldwide never ever get to write apps in the #1 category, so the issue tends to be a bit moot.
If #2, a throwaway product doesn’t warrant added effort in packaging and elaboratring on what is it supposed to be doing.
If #3, the situation is as follows: it would be ludicrous to attempt to build a critical business app without proper due dilligence in requirements gathering. Such dilligence will result in a comprehensive set of use case scenarios. These scenarios will then be used for design, testing and user training. And there’s your full fledged documentation.
comment at 20. September 2005
Richard Dyce:
Hmmm, not sure I agree. Would you argue that Agile programming is only relevant to items 1 and 3?
comment at 20. September 2005
alexbunardzic:
Richard Dyce wrote:
“Hmmm, not sure I agree. Would you argue that Agile programming is only relevant to items 1 and 3?”
Agile developement is relevant to anything, but it depends on the stakeholders’ needs. If you want it inexpensive, fast and satisfactory, you must consider agile. If, on the other hand, you prefer ritual peppered with lots of ceremony, agile may not be the way to go.
If you want a throwaway app, agile is definitelly the way to go, because ritual will slow you down.
comment at 20. September 2005
Richard Dyce:
Alex, I laughed my coffee up the wall. I hate ritual - and USDP seems to be just that. What I’m after is something that makes sure good documentation is in place, without macho “the code is the docs” posturing, and without having to go through Blairite focus group mumbo-jumbo. 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.
comment at 20. September 2005
alexbunardzic:
Richard Dyce wrote:
“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’.
comment at 20. September 2005
Bill de hOra:
The thing about software systems in production is that there’s so much going on, even if you did document it well, it still takes ages to comprehend and to figure out what’s really important. The thing about software systems in design is that there’s so much going on, even if you did document it well, it still takes ages to comprehend and to figure out what’s really important.
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.
comment at 20. September 2005
Richard Dyce:
Bill, I think that maybe what I’m trying to get at - going from documentation to tests to code rather than having so-called documentation ’show up’ from code. The problem with automatic documentation is that it seems to me to be a process of “hey, we can do cross-referencing, so we’ll call that documentation, and if people want add other stuff in then we’ll let them”. And of course it’s the other stuff that’s really useful - the docs for System Y that your CTO talks about.
Perhaps I’m talking more about getting an architectural view of the system, rather than documentation per se. Some UML stuff is good for that, but it seems that its an adjunct to XP, rather than a useful part of the process - so it doesn’t get done.
Useful documentation should be comprehensible to the intelligent layman. I may not know how to design a house, but I can get a handle on whether or not the bathroom is in the right place (and how to get there!) if someone shows me the drawings.
comment at 20. September 2005
Ryan Tomayko:
I’m feeling this.
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.
comment at 20. September 2005
Paul M. Jones:
Bill and Ryan –
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.
comment at 20. September 2005
Harry Fuecks:
To me what seems like a good compromise would be integrating generated API docs with a wiki.
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
comment at 26. September 2005
Richard Dyce:
Harry, that looks like a great idea. Still haven’t managed to get phpDocumentor running under 5.0.5 on this G5 yet though :-(
comment at 26. September 2005
Harry Fuecks:
Richard, I’ve looked at modifying phpDocumentor to spit out wiki pages using Dokuwiki syntax and… found there was a sharp learning curve before it was even possible to get a simple prototype working. That’s not meant as a criticism of phpDocumento but the problem is phpDocumentor is pretty heavyweight these days. And PHP 5.0.5 may be a can of worms for older projects.
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.
comment at 27. September 2005
Richard Dyce:
Harry, sounds like a plan. I’ll see if I can get phpDoctor up and running on 5.0.5 and have a look. (This week my free hour is scheduled for Friday ;-) )
comment at 28. September 2005
hxa:
Following my advocacy of the Unified Software Development Process with XP, I wrote a short article on a simple documentation format.
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)
comment at 07. October 2005