Relative difficulty

[jducoeur]

[Happy birthday to editrx!]

Writing code is easy. Writing documentation is hard.

Just a quick status report: the CommYou alpha is toddling along decently well. I'm ruthlessly triaging bugs and stories, and I think it's getting decently non-sucky. I'm currently in the middle of writing the documentation, which is taking far longer than I'd originally expected. But if there are no major snafus, I should have something for people to come seriously play with in the next week...

Comments

[dsrtao]

I'm not a serious programmer -- I'm a sysadmin and network guy who writes programs and scripts.

I write all my code by writing the documentation first. If I add a new feature, or change behavior, it starts with documentation. Code comes second.

Obviously this doesn't work for everyone.

[jducoeur]

I almost always write tests, sometimes first. Doing documentation first as well is more burden than I can afford.

Besides, I don't think it's a great way to produce good end-user documentation: it easily leads to fragmentation and incoherence. To make things clear, I really need to have a good gestalt understanding of this feature in context, and that often requires writing the docs for a suite of features together, once they're all implemented and I have the wrinkles ironed out. Writing the documentation first, before I've found out how things need to be tweaked to work *well*, is a recipe for inaccuracy.

Granted, this may work decently in your space, where the script is taking very specific inputs and creating very specific outputs. But in end-user software, getting the fiddly UI and behaviour details right is often 2/3 of the problem, and it's rare to guess those details correctly at the start...