Yes, I have seen the notice “Code is fact – Documentation is fiction” on the wall of the office of a team of software developers.
Which begs the question –
How is software documentation produced?
Or, to put it another way, how do we write anything?
The very first writings were possibly the records of the spoken word – people told stories proclaiming events which may have happened. On the other hand, the story tellers may have spoken about things which were nothing more than fantasy – in other words, fiction …
Currently, we either discuss whatever in a group and, someone records that discussion as written text.
Or, we simply sit down alone and, dream up a text – which may well be fantasy.
Software documentation:
What’s better?
Someone sits down and begins writing the documentation.
A group discusses what the software shall do/achieve and, someone records the discussion and, transforms the discussed items into documentation.
During the coding, the programmers include comments in the code which form the basis of that product’s documentation.
One of the above points includes the spoken word –
Speaking with each other has been around longer than writing and, is still a powerful method of achieving a consensus of what shall be done and, what shall be achieved.
Software development in isolation:
If, a lone, single, person develops a software product – or, any product for that matter – does that product stand a chance of being reliable with predictable behaviour for the end-user?
I suspect that, without human discussion – speaking with another – it is unlikely that, anything produced in isolation will be something of value.
With the exception of fiction and, fantasy and, art …
I’ve done a few one-person-projects and I consider these as rather successfull, viewing the time they remain in use.
BUT
I spent more time talking to the end users, both in person and per document/email than I did developing and testing the product. It is the hardest thing to find out what the end user really need. And that is more than often not what they ask for.
I usually begin by finding out what and how they run their business/administration/whatever and see for myself why they cann’t go on as before. From there on I start querying them for their needs and wishes keeping my eyes wide open for internal contradictions.
And secondly, sit together with the end user on your finished product and write a manual with the experience collected.
And thirdly, keep the architecture as open as possible for later changes. And these can go both ways: deleting things that after all are not important and simply not used, and new demands.
Under the rubric of “Know thy audience”, are you talking about code documentation for the benefit of maintainers/developers, or are you talking about user-facing documentation? These are two wildly different audiences with equally different needs.
I’m not a coder, but I’ve built software tools by myself. In fact, for a previous job where I was an inventory auditor, I built half a dozen different tools all by myself, maintained them all by myself, and when other people used them, they were just as happy with what they did and the reliability of them.
Like all commonplaces, there is some truth. But I’ll give you another one: good coders aren’t by definition good teachers nor writers.
And about types of documentation: a user of an application is not helped by code documentation. And code documentation, I don’t know anymore with the current tools. In olden times when I wrote in assembler, then code documentation was 100% needed, but I don’t see it that way anymore when writing SQL.
