Love documentation

One of my mates was asked if he likes documentation in a recent interview.

“No, I hate it” was his reply, or ‘I rushed so fast to get the no out that it almost came out as on’.

Hmmm, career limiting I thought.

Hmmm Hmmm, it only limits you in careers doing the type of job you don’t want though. Hmmm…

Me, I love relevant and useful documentation. Well, I think I would if I ever saw any.

Dick over on DDOE had a relevant interesting post recently. I was going to comment there, but after deleting two out of control rants I gave up. This point is very relevant having just binned my last role.

I look forward to hearing from the people who took over from me (if we are still friends ;-) ) what they think of my legacy. But I assume it will be like any builder who comes to your house. They always criticise the work of those that went before. That’s not to say I could have done a better handover. Or done some other stuff better either. (We found an error in some of my test SQL on my last day – it’s not my first or last error I’m sure).

My big point on this though is that Excel is best for tactical short term systems. And the dev process should match that short term, medium risk, medium value return. Heavyweight development processes with a documentation focus are inappropriate imo. Yes many of these things become business critical over time, at which time they should be reviewed/migrated with that new status in mind.

Anyone looking for a tactical Excel developer who loves documentation has got the wrong end of the stick I reckon.

Smurfs guide to good Excel system doco:

  1. one paragraph description of what the system does from a business pov
  2. a couple of pages of design overview about the big technology lumps that address those business needs
  3. One sentence description of each worksheet, easy to find in each sheet
  4. explanation of any complex formulas or queries
  5. Meaningful variable and procedure names in code, table, query and field names in databases

Developers can work the rest out if and when they need to.

Too much documentation is written for managers who don’t understand the business problem being addressed or the technology used to address it.

Sorry but its not realistic to fix those two fatal flaws in one word document no matter how long and involved it is. If as a manager you feel the need to understand all that stuff then learn it yourself don’t burden your devs with your education. And whilst you are at it review how you see your role as a manger – perhaps you could just trust the experts in each area and actually ‘manage’?

Generally I think devs hate documentation because so much of it is pointless. At my last job my manager kept asking me for more documentation, I kept asking if they had read the stuff I had already done? No, was always the answer. Read it and tell me what you think is missing I would say in a groundhog day style weekly cycle.

how much do you like documenting your systems? recieving documentation on projects you take over? whats your definition of useful doco?



11 Responses to “Love documentation”

  1. Mike Staunton Says:

    In the VBA code that I write for my students one way is to stick very closely to the original academic paper that I’m trying to replicate – short variable names that include relevant equation numbers is one approach that I use

    I’m also involved in a daily process that involves tens of thousands of 1970s Fortran code running on UNIX – thankfully the two original programmers are still alive and well, so we get together for weekly maintenance and development chats; here the most crucial documentation is NOT how everything works but instead it is what to do in an emergency when things DON’T work (and that only comes with experience of previous problems)

  2. Hiran de Silva Says:

    I’m right there with you Simon. The solutions I build are in collaboration with the operational managers/users – IT usually have no idea until when it (often/always) ends up as a business critical enterprise process. Then we have the ‘where’s the documentation’ scenario when they are ordered to support it. Of course, the whole story of the solution is in all our heads, it developed out of ‘playing with ideas’. To explain what the solution does needs understanding things that while being second nature to us (business users) are quite alien to the IT guys. That includes VBA often.

    Here’s one attempt at starting a Wiki-like documentation as an answer to the need for docs. The idea was that the dev team (ie. me and the users) contribute what we know in flowcharts etc and keep up to date.
    (password: ramjam9x. I’ll change that in 48 hours).
    But IT refused to host it, instead asked for a Word doc which now sits in a folder where no one looks, probably grossly out of date by now.

    BTW you can see some of the doc tools I have used (DocumentX2010, ProjectAnalyser9, Visustin). I’m experimenting with Joomla and online flowcharting for collaborative documentation.


  3. Hiran de Silva Says:

    Mike makes a good point. It’s what to do when things DON’T work. To us (me and business users) it’s easy. But to get someone else to get to that level of understanding … hmm.

  4. Mike Woodhouse Says:

    I’m having a documentation “discussion” with our IT folks at the moment, regarding what I will (or won’t) deliver. I’m happy to provide information that is relevant to the task that will be performed, so I’ll be linking sections of code to the (PDF) model description that they implement. I may write a couple of lines per class if there’s some specific point in my (C#) code that the readers (mostly COBOLlers, don’t ask) that needs to be clarified.

    Oh, and I may make a picture. Beyond that, the massive XMLDoc-style nonsense that they want is up to them.

    Some questions that mioght be asked:
    “Who will read this?”
    “Why will they read it – what task are they going to perform that requires that they read it?”
    “When they read it, how confident will they be that the documentation is up-to-date?”

  5. AlexJ Says:

    This is a great example of a cautionary tale for consultants – you had better clarify (and document) the client’s doc expectations before signing the contract. You could easily wind up in indentured servitude when the effort of doing the doc is ~= the effort of doing the app.

  6. Simon Says:

    I tend to plan things out on paper. On one of my docs I took a photo of one of my diagrams and included it in word.
    The mcManager was outraged. That should be in visio she said. Feel free I said…
    The point being if there is value in visio drawings for her she can redo my handdrawn effort, there is no value for me, I have already moved on to the next stage of development. and hand on heart I know the work to convert to visio will provide less than zero business value.

  7. Charles Williams Says:

    I may do several kinds of documentation, depending on the size and scope of the project:
    – Requirements definition (this is what we agreed it should do: never gets updated by reality!)
    – Estimate/quote
    – Instructions for the Administrator (Control tables, security and Version Control etc.)
    – User guide/Help (what the commands do etc.)
    – System guide (how the system components fit together, database and query stack etc.)
    – Comments in the code.

    When I get asked to modify something I had forgotten I ever developed, 10 years later, (this actually happened the other day), I find this stuff useful.

  8. Patrick Says:

    The doc I would *like* to have when I take over would tell me
    1) What the business problem is – assuming that as a dev I’m new to this business area. The requirements, as Charles says.
    2) The architecture – where to begin, a guide through its data structures and any non-trivial algorithms
    3) The operating cycle – daily, weekly, beginning of month/year routines
    4) Known gotchas and cautions, as comments or text boxes, obsolete or test code being marked as such.
    5) Test cases and results (dream on…)

    Yes, I can read the formulas and code but that tells me HOW something is being done rather than WHAT is being achieved. I can read the mechanics but not the intent.

    I saw two systems last week:
    One a coding horror of incompetent VBA and a mess of formulas with constructs like OFFSET(INDIRECT(rangename),0,0)
    The other, a highly structured spreadsheet containing all the business logic in the form of a dozen SQL statements and table definitions and no VBA, just an add-in as a driver.

    I can read the second, the first is guaranteed frustration.

    But without documentation, I still require to understand (and document for the NEXT tech support person) the user’s requirements in their terms in order to know whether either is actually a solution to their need.


  9. Matt Says:

    I agree with Patrick.

    I think from a personal point of view the kind of documentation I would want to see were I to step into someone elses shoes would tell me WHAT the system does and WHY. As Patrick just said, I can read formulas and code but it’s much more useful to find out the reason behind it. If I can understand the business processes I have a better understanding of code and formulas if they break/if people want systems tweaking.


  10. Bob Phillips Says:

    No comment :)

  11. Simon Says:

    ‘No comments’ ?
    That must be the first time we’ve agreed Bob!!

    Patrick/Matt, Thats pretty much what I meant in my guide
    Charles, I know what you mean about that initial requirements, I re-read one of mine recently and realised just how little I understood the problem at that point in time.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: