Only Five Types of Documentation?

Somebody, who, if they are a developer by nature, hasn't done any software engineering theory for quite some time, recently pointed out an article on the five types of software documentation, being
Requirements
Architecture & Design
Technical
User
Marketing

I thought about this for a few seconds, with the usual "But what about ...?" question dangling from my lips. Then I realised the problem - there are possibly five different skill sets in the five types of documentation listed, being
Business Analyst
Software or System Architect, Project Manager, Team Manager
Software Developer, Tester
Technical Writer
Marketer

These people do sometimes talk to each other, but there is no direct link, and very few tools for conveying one set of documents to the next recipient in the chain - because it is a chain! These documents are distinct elements in different parts of the product development life cycle (nothing to do with software). They are produced by different people in different places. They are an outcome of (any) product development. They are not the end goal. In fact, many products are developed without several of these types of documentation (to their detriment, I must say).

Without requirements, a product has no meaning. It's just a thing that is waiting for its application, a useless mass. The old "If you build it, they will come" is meaningless, because they may not be able to find you. Kids who develop war games in their spare time believe that there is a requirement for badly-conceived games, and that gets them well onto the wrong path.

Without architecture & design, a product has greater potential for failure, both in terms of the project being over-budget & late, and the product itself being faulty. Without a plan for how to build the product, the effectiveness of anything built is purely coincidental.
In a professional product development environment, this area is big. It starts with functional requirements, product architecture roadmaps, product roadmaps, project management, and budgeting, and goes on to high level solution design, low level design, software design (in this case), development guidelines, processes, test plans, ... The list goes on. This is planning. It's what people do badly in product development. It takes many people with different skills.

Without technical documentation, a product is almost useless, and can quickly be forgotten. There is no potential for maintenance if all of the design decisions are in the head of one person, or else they live their lives vicariously through the extended utility of their one product. If anything goes wrong, there's no easy way to determine how to fix it, why things were developed the way they were, etc.
I'll also throw testing into this basket - test implementation & results, without whom we have nothing worth releasing into the wide world.

User documentation means that someone can figure out how to use the product. Without it, no-one will. Without being able to understand the documentation, no-one will use the product. And yet, we continue to leave this up to the product developers to create. This step requires professionals.
Without users, there is no need for support, or for issue resolution libraries.

Similarly, marketing documents should not be created by product people or over-zealous executives who think they know better, but by professionals who know how to portray products in the market place. It's not a matter of portraying the product so much as creating the portrayal. Without marketing, a product will never be 'discovered'.

I won't quote the article, because it was so generic that it's hardly worth blowing out of the water. If it was written from a software developer's perspective, then it failed to understand the small part that a developer plays. If it was written from any other perspective, then it failed to understand the small part that a developer plays.
Let's rephrase the five levels of product development:
Need Discovery
Planning
Implementation
Maintenance & Support
Marketing & Sales

Document that.

Step Away from the Keyboard!

I cannot stress enough the importance of not writing code. Relatively speaking, writing the code is a very small part of implementing a solution to any problem, whether it's new product, adding functionality, or debugging.

The first step is always understanding the problem. In the case of new work, that means understanding the requirement, and understanding the person who proposed the new functionality, the client, or other recipient of the finished product. If you don't do that, then there's no point going into ecstasies of UML in describing a solution. It's wasted effort.
Good requirements lead to test first development, which means writing (which may look like coding, but really isn't) good tests to fail, and getting those right such that they cover the solution space.
Then you can think about designing the code solution that will satisfy those requirements and fit into the overall architecture, following design rules, coding standards, etc. This must be documented. If you can't write about it, then it's not worth implementing. Just the act of writing, or discussing it with someone else, usually opens up new vistas of thinking about the problem.
Now you can code it (and improve the tests).
Testing of that solution has to take some time, too - and it's not a hit-and-miss process of running the debugger to step through each line, make changes, start again. Each time something goes wrong, go back & work out where it went wrong - in the design of the solution, the overall architecture, the understanding of the requirements, ...

Maintenance is the same, except that you have a different start point - the problem is that a requirement is not being fulfilled; tests are not correct (they hadn't found the problem). Therefore, the code is wrong.
Caught you! The code isn't wrong yet. The requirements were not understood, the architecture was inappropriate, the design was incorrect, the documentation is not sufficient. The implementation is again a minor detail.

I'm sure I mentioned coding in there somewhere. It was a small thing. Anyone can code, with the right training. It takes experience, skill, & intelligence to produce solutions to problems.
Software developers - the craftsmen, the artists, the engineers of the industry, happen to be able to code. It is not necessarily their job.
Developers should be able to ask questions, discuss, argue (in the Greek sense, not street sense), draw, write (whole sentences & paragraphs), think, and love their work.
Anything less is a drone.

Scribo Ergo Sum

Unfortunately, this doesn't really have the same dual meaning as in English. "I write" can imply both the written word (or typed), & the process of developing software (which some developers never use anything but the keyboard for - a mouse being a mere distraction).
But this is not related to what I'm here to discuss, except obliquely.

Developers develop software. They tend to believe that that is their raison d'être (Latin, & now French - how posh!). This has something to do with the fact that, "The moving finger writes, and having writ ..." (Arabic, no less - albeit translated) gives ownership of the creation to the fingers. Fundamentally, if you didn't write it, you don't own it. This gives rise to the old NDH label (not developed here) to indicate something to be spat upon as unworthy of gracing a developer's concerns just because they didn't write it.

This is all, of course, a load of cobblers.

Developers who do no more than write software are process workers. They are told how to put things together, are provided with the materials, & never have to think for themselves. Such drones are useless. They no more own their output than a factory worker owns the fluffy toy for which they sewed on an arm, or a labourer owns a bridge on which they rivetted.
The ownership of the toy goes to the designer. The owner of the bridge is the architect or engineer who conceived or oversaw it. The owner of software is not the one with the fast fingers, but the one who understood the customer requirements & drew the pictures & wrote the specs that described the solution. Everyone else is merely a contributor.

This leads me to latter phases of software development. All developers hate maintenance, mostly because it is soul destroying to see a piece of software that was once designed & developed well for one purpose be systematically 'improved' for new customers (bespoke work) or mangled for new industry requirements (bloatware). Good developers know that this is bad. However, maintenance is an essential part of the life cycle of software, & cannot, in itself, be considered beneath the concern of the professional.
What is missing is a sense of ownership. How can you own the product being shipped if it has had a history of owners who have developed little add-ons to someone else's design from the mists of time?

Own the problem. Own the solution. Own your work. Be proud of what you can achieve, given the trying circumstances. Make your work important. It's all up to the developer.
Sure, this may also be a part of the project management process, ensuring that there is something worth owning, & that the developer is not treated like a drone fulfilling a silly requirement in a mindless manner.
Engage. Be engaged.

Peter FitzSimons tells a story that I believe he attributes to Alan Jones about the difference between making a contribution & making a commitment. If you're having bacon & eggs for breakfast, the chicken has made a contribution; the pig has made a commitment.

Own the solution, regardless of who writes the code.

Magicians of Code

In general, software developers are expected to be magicians - miracle workers, at the least. I say this with the expectation of being shot down with a spray of non-technical folks' spleen. But with a revelatory zeal I will explain myself further.
I will always contend that developing software, as a profession, is artistic, in that developers create their solutions to real-world problems using techniques learned and passed on by masters, tried experimentally in many projects, improved on, and occasionally discarded as no longer effective. This is not science, in its strictest sense, fundamentally because there is no absolute, no truth sought. This is art.
However, like the great art of old, and unlike amateur art, developers' creativity is usually hampered by their patrons - the exigencies of the business environment, such as time & resources. This should come as no surprise.
Therefore, a developer is expected to create beauty out of something that is generally not sufficient, and is often ugly. They are expected to do it devoid of inspiration or the vagaries of muses. They are given a fixed canvas, limited assistants, and often even only a small palette, and are expected to create a masterpiece every time.
Heaven forbid that someone should point out that art just doesn't work like that!
Then there's the argument that usually comes from frustrated project managers with no background or experience in the arts, that a bridge can be built precisely with known materials, planned to the micron, etc. How often have I told such a project manager to go build a bridge & get over it?
Software developers don't build bridges. Bridges don't solve business problems.

I used to have one such project manager - an inherently stupid & lazy man, but that's just my opinion. I tried to explain to him that what we did wasn't work with steel girders, but it was like rearranging the atoms to invent a new kind of steel each time. He didn't get it. After this, I put a sign on my cubicle which read "Alchemical wizardry applied within". He never asked for an explanation.

And still, each time a project fails - either in being late, over budget, or not fulfilling all of its requirements - it must be the fault of the developer who must be inherently ineffective (or incompetent) if they can't deliver the promised project. Obviously. Writing software is so beneath project managers that they could not stoop to do it. Well, there are those who once wrote a pascal program, and that was a snap. It added two numbers & got the right answer. That could be done in less than a day ...
There is no answer. There is no question. There is only life & its experiences. And there is death.
A project begins. We use what we have learned; we learn more; we help others to learn from us. A project ends. Whether we have led a good project or not is not judged by our success, but by the weight of our souls against a feather on the scales of fate.