6

How important is a documentation? or a spec for that matter?

I've been writing software professionally now for about 5 years. Each new job I start I am more often than not faced with spending a few days reading the code trying to figure out how everything works, taking notes, and eventually producing the documentation I wish I had at the start.

Some of these companies are quite well known and I've been amazed they don't have enough documentation.

Is this something anyone else is familiar with?

  • What do you put in this document you create? You would then have a more specific question(s) about why this isn't typically done. If one programmer can come out of the cold and write meaningful documentation in a few days, it seems that most projects had enough slack time for someone who was on the project to create. Nothing against you, but I'd think they could have created it in less time since they should know more about the project. – JeffO Dec 8 '16 at 22:37
  • 1
    What documentation do you leave behind as you go from one project to the next? – JeffO Dec 8 '16 at 22:38
  • The question is: is the documentation made from code or the code from a documentation? It should be the latter, but in practice it's the first. That's why documentation always sucks. – qwerty_so Dec 8 '16 at 23:09
9

Everyone agrees that documentation is important.

However...

Many programmers believe that code should be "self-describing," that the code itself should act as the documentation, and that therefore you don't need documentation. But that's only true to a certain extent. Code does not adequately document the relationships between components. It's unreasonable to ask the programmer coming after you to wade through a 100,000 line code base trying to figure out what all those abstract factory factory factory objects you wrote are supposed to do.

Documentation takes time. The first priority in most companies is shipping, not documentation. When there is documentation, it often documents their business processes or provides a user guide, but not the relationships between software components.

Documentation is another thing that must be maintained. Unlike self-documenting code, documentation must be kept up to date, otherwise it will no longer agree with the code (which is the real source of truth).

For all of these reasons, documentation is often neglected.

  • 1
    In addition to (and in my opinion, superior to) self documenting code, good tests make great documentation. They can document how components behave, how they are constructed, and their relationships with other parts of the system. – Angus Goldsmith Dec 8 '16 at 16:57
  • 1
    @AngusGoldsmith, 100% agree. The code documents what; the tests document the why/how, which is at least as important. – David Arno Dec 8 '16 at 17:19
  • 1
    That's easy to say. In the real life, the code is more likely the "The Dead sea scrolls". – Laiv Dec 8 '16 at 18:36
  • Even after reading the documentation, you'll have to read the code anyway just to make sure the code does what the documentation says. – Eric King Dec 8 '16 at 20:55
7

Up-to-date, correct and well-designed documentation is a must. However, if it doesn't fulfill those three criteria, then it's worse than useless: It's a time/disk/soul-sucking hell.

One of the problems I find in medium/large projects is that there is a fetish about documentation, but absolutely no notion of what documentation is for, namely:

  • Documentation is not a tick-box.
  • Documentation is not a Microsoft Word "document" containing mostly boilerplate screenshots of the installation/configuration wizard. (99% of the "documentation" I find (or is requested of me) is of this kind).
  • Documentation is an annotated live graph of all relations (both in-system and external flows).
  • Documentation is a live wiki that's collaboratively build by all the stakeholders of IT. Note that I didn't say project.
  • Documentation must include all the configuration options, and for each one, it must specify which value it has or exactly where and how that value can be acquired.
  • Documentation must also state why option X has value Y, and whether the decision was technical (e.g. we're using jumbo frames because it increases performance and reduces system load) or political (e.g. we're not using auto-negotiation because there were some bad experiences on 20-year-ago Version 0.0.1 cards/switches).

As much as possible, don't "document". Do a graph, document it on the wiki and load the data from a CMDB.

  • 3
    Agreed, bad documentation can be worse than no documentation at all. – Robert Harvey Dec 8 '16 at 18:11
1

The point is the document is far more useful to you (the new guy) than the people who have been working on it for years. I've produced similar documents and even maintained them for a while; but I suspect if someone tried to pick up from me they'd face difficulties.

  • 1
    Ideally, documents to help with a transition should be written, read by the new member(s) with the chance to ask questions, get clarification, etc. Then an update should be made to avoid misunderstandings. I try to do this when I write directions. – JeffO Dec 9 '16 at 23:58

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.