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.
Subscribe to:
Post Comments (Atom)

No comments:
Post a Comment