Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Documentation - Good Idea or Bad?
The argument against:
Despite iterating, redesigning, and trying my hand at everything to lead users to documentation before running to the support forum with every question, repeat questions never failed to land in the support queue every day. It took me years — far more than it should have — to realize that the solution was not in the documentation and the problem was not in the user’s ability to read it. The problem was the product. If users were asking repeat questions, it meant there was something wrong with the user experience. Eventually, I shifted my focus. Instead of writing more docs, I focused on addressing the problems that continued to crop up in the software. – The Best Documentation Is No Documentation
The argument for:
What I discovered later was that design documentation, encoding the intent and decisions made during developing a system, helps teams be successful in the short term, and people be successful in the long term. Freed from fitting everything in my head, emboldened by the confidence that I could rediscover forgotten facts later, I could move faster. The same applies to teams. One thing I see successful teams doing is documenting not only the what and why behind their designs, but the how they decided. When it comes time to make changes to the system—either for debugging or in response to changing requirements—these documents are invaluable. It’s hard to decide whether its safe to change something, when you don’t know why it’s like that in the first place. The record of how you decided is important because you are a flawed human, and understanding how you came to a decision is useful to know when that decision seems strange, or surprising. – Code Only Says What it Does
Sometimes when I am going back over old code the way I have the last few days I find myself wondering “Why did I do this that way?” Or “I know this works but I really don’t remember why.” I find writing documentation to be something that I have to psych myself up into a certain mood to write but also important because it isn’t always just helping other people, sometimes it helps me when I need to refer back.
Offline
Re: Documentation - Good Idea or Bad?
Great topic.
I agree the best documentation is none. And if there is ever a need, then focused documentation at the point of use – a succinct help popup – is hard to beat. But I find high quality topic-based documentation is hard to beat as a reference if you want to go beyond the basics and delve into specifics. Well written API references, and stuff like that.
With regards code docs (and yes I’m sorry that some of Txp’s docs aren’t up to scratch yet) I’m a firm believer of documenting why something is done in a particular way than what it does. e.g. why a workaround is necessary, or why a block is necessary to code in one way versus another (perhaps due to constraints of the input that aren’t obvious at that particular point in proceedings).
Where ‘why’ is not possible or doesn’t make sense, sporadic and targeted ‘what’ comments really help orient people reading code. Stating “Loop over the records” above a while() loop adds no information. Anyone with a basic level of language knowledge can tell it’s a loop. But stating “Build the main table of links” above the loop acts as a helpful signpost when scanning the code that you’re in the place you want to be.
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Txp Builders – finely-crafted code, design and Txp
Offline
Re: Documentation - Good Idea or Bad?
I agree: a great topic. I find documenting a little intrusive while I’m trying something out – I suppose because there’s sometimes quite a bit of trial and error – but otherwise that it is indispensable. I am sometimes shocked how little I can remember of something just six months down the line! Having a note to give you a clue or trigger recall is such a help!
One thing I see successful teams doing is documenting not only the what and why behind their designs, but the how they decided.
This is good not just for documentation but for reasoning your design decisions.
Freed from fitting everything in my head
I can definitely relate to that. The same applies to to-dos. Knowing you can “forget” something “for now” because your “trusted system” will show it to you again later, or you know how to find it again when you have time, makes it easier to jettison stuff from your brain without worrying about having forgotten something. The problems begin when stuff is recorded in too many places.
With regards code docs … I’m a firm believer of documenting why something is done in a particular way than what it does…
Agree too. I’m a culprit of that in my own stuff too, and try and improve on that. The core team has different habits here too in their commit notes ;-)
I find writing documentation to be something that I have to psych myself up into a certain mood to write
So how do you make your notes, Michael? Given your background, I’d have thought you’d be an expert documenter.
TXP Builders – finely-crafted code, design and txp
Offline