Introduction
Communication of technical information between software developers is crucial. The debate about the advantages and disadvantages of written vs verbal communication has been going on for at least half a century, but even half that time ago, thorough written documentation was generally considered essential. For example, the SEI (Software Engineering Institute) released the CMM (Capability Maturity Model) around 1990 which heavily emphasized documentation of the product (as well as the procedures used to create the product).
I did a post-graduate diploma in SQA at UTS in 1993. Much of the software quality stuff was really useful (and found its way into Agile).
However, I found CMM and quality standards (like ISO 9001, etc) not that useful if not downright burdensome. They seem to me like a money-making scheme for certification organizations and consultants.
The debate usually centers around requirement specifications or specs. I have talked about the problems of writing detailed up-front specs before so I won't go into that again (see Agile Design). [However, in brief specs are incorrect, incomplete, inconsistent, out of date and just generally difficult to understand and use - this is almost inevitable, no matter how hard you try to get them right and maintain them.]
Agile reopened this debate. One of the five core principles of the Agile Manifesto is to Favor working code over documentation. This is taken by many people to mean that Agile has no place for written documentation. This is not true - Agile does not try to do away with documentation when it is demonstrably useful to the developers and it cannot be replaced with more effective alternatives. (There are often better alternatives, usually in the form of code, of which my favorite is Unit Tests).
Written vs Verbal
We will start with a recap of what I believe is common knowledge.
Written documentation is good for well-understood information that needs to be disseminated to different people, and/or at different times. Moreover, the readers (and the writers) can go at their own pace. Another advantage is that the author(s) have the opportunity to fix and refine the document and others can validate it.
On the other hand, studies show that verbal communication is much less likely to be remembered. Further, many work environments have other effects that can interfere with verbal communication such as different accents, background noise, and simply the emotions and distractions of interpersonal communication.
Apart from these well-known attributes, here are a few more points from my own observations.
Document Types
We talked briefly about "specs" above but we should clarify the different types of documents typically required for a software project. Traditionally, there are three main documents. (There may also be ancillary documents, such as project plans, test plans, etc.) I will later describe how these documents are used (or avoided) in an Agile environment.
Technical Documents
Sometimes these two technical documents are also combined, perhaps intentionally, but more often because the analyst/designer has already formed an opinion of how the software will work internally. The specs become full of implementation details, which can needlessly restrict design choices.
Communication of technical information between software developers is crucial. The debate about the advantages and disadvantages of written vs verbal communication has been going on for at least half a century, but even half that time ago, thorough written documentation was generally considered essential. For example, the SEI (Software Engineering Institute) released the CMM (Capability Maturity Model) around 1990 which heavily emphasized documentation of the product (as well as the procedures used to create the product).
Quality Standards
I did a post-graduate diploma in SQA at UTS in 1993. Much of the software quality stuff was really useful (and found its way into Agile).
However, I found CMM and quality standards (like ISO 9001, etc) not that useful if not downright burdensome. They seem to me like a money-making scheme for certification organizations and consultants.
Agile reopened this debate. One of the five core principles of the Agile Manifesto is to Favor working code over documentation. This is taken by many people to mean that Agile has no place for written documentation. This is not true - Agile does not try to do away with documentation when it is demonstrably useful to the developers and it cannot be replaced with more effective alternatives. (There are often better alternatives, usually in the form of code, of which my favorite is Unit Tests).
Written vs Verbal
We will start with a recap of what I believe is common knowledge.
Written documentation is good for well-understood information that needs to be disseminated to different people, and/or at different times. Moreover, the readers (and the writers) can go at their own pace. Another advantage is that the author(s) have the opportunity to fix and refine the document and others can validate it.
* The problem of misunderstanding written words has resulted in many problems due to hastily written emails. Often something written as a joke is taken seriously.
This is the reason that emoticons (like :) were invented, and why you should carefully read emails, and think about how they may be interpreted, before sending.
Verbal communication is good where the actual subject matter is less well-defined or understood, and/or there is a need for interaction between the participants. A commonly cited advantage is that there is often less misunderstanding due to secondary information being conveyed beyond the actual words spoken* - intonation, body language etc.This is the reason that emoticons (like :) were invented, and why you should carefully read emails, and think about how they may be interpreted, before sending.
On the other hand, studies show that verbal communication is much less likely to be remembered. Further, many work environments have other effects that can interfere with verbal communication such as different accents, background noise, and simply the emotions and distractions of interpersonal communication.
Apart from these well-known attributes, here are a few more points from my own observations.
- In my experience some people are good at learning verbally, but many are not. The best approach depends on the team and should allow for personal preferences and abilities. If you favor one approach or the other you may drive away good people.
- In a top-down, autocratic environment people are scared to make a mistake. Verbal communication does not work well since someone will not ask for clarification for fear of appearing stupid. They may also not want to repeatedly ask for clarification for fear of embarrassing the explainer.
- In the software industry (at least in my experience) there are professionals from many different backgrounds. Verbal communication can be problematic when people of different NESBs (non-English speaking backgrounds) attempt to communicate. Written communication can often avoid this problem.
- Written documentation is often used more for self-protection than in any valid attempt to communicate information. (See the case study below.)
- Finally, and possibly most importantly, the documentation produced by a team is typically written by one (or perhaps two or three) people. Other team members have no ownership, and are disinclined to modify or even use the documentation.
Document Types
We talked briefly about "specs" above but we should clarify the different types of documents typically required for a software project. Traditionally, there are three main documents. (There may also be ancillary documents, such as project plans, test plans, etc.) I will later describe how these documents are used (or avoided) in an Agile environment.
- User Manual - how to use the software
- Specifications - what the software does
- Design Document - how it does it
Technical Documents
In CMM jargon:
specs == "Software Specifications"
design == "Technical Specification"
The "technical" documents are the specs and the design. You may know them by other names. For example, the specs are sometimes called the functional specification, customer requirements, etc. What I call the design document may be called the internal design, software architecture, technical design document, etc. Traditionally an analyst writes the former and a designer creates the latter - but these are often done by the same person (analyst/designer).specs == "Software Specifications"
design == "Technical Specification"
Sometimes these two technical documents are also combined, perhaps intentionally, but more often because the analyst/designer has already formed an opinion of how the software will work internally. The specs become full of implementation details, which can needlessly restrict design choices.
Additional problems arise because technical documents try to serve different purposes. Ostensibly they are to tell the developers what to do, but in practice their main audience is the client. First, they they must be comprehensive and sound authoritative to give the client confidence that the project is on the right track. Another purpose is to protect their writers. (You can tell this sort of document by the large number of exclusions, restrictions, provisos, assumptions, and client responsibilities -- for the writer(s) to later point to, when the client is unhappy -- and by the fact that they have to be "signed off" by a large list of stakeholders.)
Design Document
In previous posts I talked extensively about the problems with big up-front specs (see the section called Problems of BDUF in Agile Design). A different problem is that the design document is typically underdone. (This happens even, or especially, in an Agile environment as I discuss later.)
Most of the projects I have worked on in the last three decades had absolutely no design documents. Some possible reasons were:
Agile
Many Agile proponents take the approach that technical documents should be just sufficient and no more -- I call this MVD (minimum viable documentation). The problem with MVD is you can get away with providing no design document whatsoever, unless there are contractual requirements. MVD is short-sighted as it creates huge maintenance problems down the track, especially once the original developers have left.
So how should you approach documents in Agile? I will look at it from three different angles: who, when, and what. The nice thing is that all ways of looking at the problem lead to similar conclusions.
Who
First you need a clear idea of who a document is written for. Technical documents (especially those that need to be "signed off") have more than one audience which muddies their purpose. A simple example is that have a lot of detail (superfluous for developers) intended to ensure testers consider all scenarios.
However, the main problem with specs is they are primarily intended to make the customer happy. First, the specs must be detailed to give the client confidence that the developers know what they are doing.
CASE STUDY
I was attempting to wean the team off detailed written specifications. It was assumed that the client required detailed specs but we found the client was quite happy to work closely with us to create user stories each accompanied by a few acceptance criteria. This was a revelation and even a relief to most of the developers but I still had one experienced developer who was vehemently opposed. After some discussion I discovered why. Here is his story...
My colleague had worked for over a year on a large project which was finally delivered. Apparently, this was not a typical waterfall project but the contract did require a large detailed specification to be signed off by all relevant stakeholders. After almost two years the product was delivered but the client was unhappy. There was a large gap in the design. They argued that it was a major oversight that should have been avoided or at least discovered much earlier. My colleague was the scape-goat for the problem, being responsible for much of the analysis and design. After scrutinizing the design document he was saved by one small sentence which implied that the "gap" was explicitly not covered. Since the client had signed off on the document they were clearly the ones at fault. One small sentence in the specifications (not even written by him) saved my colleague his job!
I was attempting to wean the team off detailed written specifications. It was assumed that the client required detailed specs but we found the client was quite happy to work closely with us to create user stories each accompanied by a few acceptance criteria. This was a revelation and even a relief to most of the developers but I still had one experienced developer who was vehemently opposed. After some discussion I discovered why. Here is his story...
My colleague had worked for over a year on a large project which was finally delivered. Apparently, this was not a typical waterfall project but the contract did require a large detailed specification to be signed off by all relevant stakeholders. After almost two years the product was delivered but the client was unhappy. There was a large gap in the design. They argued that it was a major oversight that should have been avoided or at least discovered much earlier. My colleague was the scape-goat for the problem, being responsible for much of the analysis and design. After scrutinizing the design document he was saved by one small sentence which implied that the "gap" was explicitly not covered. Since the client had signed off on the document they were clearly the ones at fault. One small sentence in the specifications (not even written by him) saved my colleague his job!
Design Document
In previous posts I talked extensively about the problems with big up-front specs (see the section called Problems of BDUF in Agile Design). A different problem is that the design document is typically underdone. (This happens even, or especially, in an Agile environment as I discuss later.)
Most of the projects I have worked on in the last three decades had absolutely no design documents. Some possible reasons were:
- it simply didn't occur to anyone to document the design
- the specs already included much of the design
- the developers created the design on the fly and never got around to documenting it
- the developers simply found it too hard to put technical details into words
- there was nobody willing and/or able to write the document
- the developers thought the implemented design was "self-describing"
- there was unwillingness to document something that was likely to change
- there was unwillingness to write something that would be criticized or simply ignored
- management didn't ask for it
- don't know the document exists
- can't understand the document
- have no incentive to understand it
- think it is incorrect (even when it isn't)
- believe it is out of date, especially as the original author(s) have left
- feel no ownership and so will not update or even read it
Agile
Many Agile proponents take the approach that technical documents should be just sufficient and no more -- I call this MVD (minimum viable documentation). The problem with MVD is you can get away with providing no design document whatsoever, unless there are contractual requirements. MVD is short-sighted as it creates huge maintenance problems down the track, especially once the original developers have left.
So how should you approach documents in Agile? I will look at it from three different angles: who, when, and what. The nice thing is that all ways of looking at the problem lead to similar conclusions.
Who
First you need a clear idea of who a document is written for. Technical documents (especially those that need to be "signed off") have more than one audience which muddies their purpose. A simple example is that have a lot of detail (superfluous for developers) intended to ensure testers consider all scenarios.
However, the main problem with specs is they are primarily intended to make the customer happy. First, the specs must be detailed to give the client confidence that the developers know what they are doing.
“for the developers,
by the developers”
by the developers”
Just as important though is who is the document written by. A document is not fully utilized unless the users of the document feel they have ownership of it. (It also makes it much more likely it will be kept up to date.) For the team to have ownership the team needs to write the document. Not just one or two people but all the developers need to contribute.
In summary, you need to be clear on the document's audience and purpose. Technical documents need to be written for the developers, by the developers.
When
The problem can alternatively be seen as one of timing. As we saw above, the purpose of many documents is mainly to demonstrate to the customer that the team know what they (the customer) wants and know how to give it to them. Hence the document is detailed but all this detail is provided much too early which invariably locks the project into a design, which is invariably not the best design.
In large waterfall projects mountains of documents were often written in the analysis and design phases even before the programmers had joined the project!
On the other hand real world projects before Agile were typically not done anything like that. Developers had to (and sometimes even wanted to) produce documentation but to avoid having to continually modify it to match the changing design (or have it become out of sync) most teams left writing design documents till the end of the project. Unfortunately this is the time when the team probably has little time and motivation to write it, or those who started to write it had left, etc.
The Agile approach is one of JIT-design. Design is not done until needed. This is the Goldilocks time to update the documentation - not too early and not too late but just in time.
I will note here that this is another classic case of DIRE. The developers should be documenting the design as they build it. Of course, this does not mean updating the document whenever any aspect of the design changes. The code itself is the "true" documentation, but looking at the code is not useful for getting a high-level overview. As I have mentioned many times before Unit Tests are very useful for documenting the behavior of modules and how interfaces are meant to work (see the section on Documentation in Unit Tests). However, at the highest level it is important to update design documentation that reflects major changes, particularly if they are core and not likely to change in the future.
What
On the other hand real world projects before Agile were typically not done anything like that. Developers had to (and sometimes even wanted to) produce documentation but to avoid having to continually modify it to match the changing design (or have it become out of sync) most teams left writing design documents till the end of the project. Unfortunately this is the time when the team probably has little time and motivation to write it, or those who started to write it had left, etc.
The Agile approach is one of JIT-design. Design is not done until needed. This is the Goldilocks time to update the documentation - not too early and not too late but just in time.
I will note here that this is another classic case of DIRE. The developers should be documenting the design as they build it. Of course, this does not mean updating the document whenever any aspect of the design changes. The code itself is the "true" documentation, but looking at the code is not useful for getting a high-level overview. As I have mentioned many times before Unit Tests are very useful for documenting the behavior of modules and how interfaces are meant to work (see the section on Documentation in Unit Tests). However, at the highest level it is important to update design documentation that reflects major changes, particularly if they are core and not likely to change in the future.
What
So what does Agile documentation contain?
It should always record the current state of the system, not some past state or a future proposal. As I mentioned above, it is owned by the team and updated with the code. The documentation is focused on the customer, as it reflects system changes that are driven by the backlog.
What does it not contain?
You can tell a document is not "Agile" when it is used to tell people what to do. For example, the traditional specification is written by the analysts/designer to tell the programmers what they are to do. Another clue is that it contains lots of disclaimers and provisos and its main purpose is to gain the client's approval.
The author of this type of document is focused on the document itself (and how it is perceived) rather than the success of the product. In other words, it has to be nicely formatted according to company standards, appear complete and authoritative and signed off by all stakeholders.
How
As a bonus I will give an example of how a design document may be created for an Agile project.
As a bonus I will give an example of how a design document may be created for an Agile project.
- Initially, the developers gather a few user stories and create a simple first version of the software. There is no design documentation as it is easy enough to understand it by inspecting the code. The team have yet to decouple any parts of the system since it is not yet clear why or how to do so.
- As the system grows it becomes obvious how to (but more importantly necessary to) divide the system into modules. How these modules work is "documented" using a comprehensive set of Unit Tests, not written documentation. However, the team needs to create a brief design document that explains the overall design, in particular why it was necessary to decouple certain areas.
- As the system grows many more modules will be needed. New modules will be added or existing ones split as the need arises. The design document is updated by the team as the actual code is updated. This sort of documentation is invaluable for new people joining the team and even for existing team members as the design becomes more complex.
Finally, I should explain the vital role of code in the documentation debate. As the saying goes the best information comes "straight from the horses mouth". In software development the actual operational software is the "horses mouth". To extend the, admittedly poor, analogy Unit Tests might then be the "jockey"; Unit tests are also code which interfaces directly with the "horse".
More traditional documentation is getting further from the horses mouth. In fact most that I have encountered is akin to an ill-informed tip overheard at the local pub.
Getting back to the point. You often don't need written documentation since the actual behavior of the software is a better form "documentation". Further, Unit Tests demonstrate how modules can be used, are often easier to understand (and can even be stepped through in the debugger), are typically more comprehensive (especially with regard to error-handling) and are never out of date (if run regularly).
OBJECTION
An objection I often get: "I think the software is doing the wrong thing. How can I check if there is no written document describing what it should do?" My reply is: "What do you think it should do? And more importantly, what does the customer think it should do?"
However, sometimes the customer doesn't care and the behavior is determined by external reasons, such a technical limitations, government regulations, etc. Sometimes UAT (user acceptance test) scripts can document the correct behavior - but UAT scripts have a habit of quickly becoming out of date.
In many cases this is a valid objection and a good example of why documents are still required.
An objection I often get: "I think the software is doing the wrong thing. How can I check if there is no written document describing what it should do?" My reply is: "What do you think it should do? And more importantly, what does the customer think it should do?"
However, sometimes the customer doesn't care and the behavior is determined by external reasons, such a technical limitations, government regulations, etc. Sometimes UAT (user acceptance test) scripts can document the correct behavior - but UAT scripts have a habit of quickly becoming out of date.
In many cases this is a valid objection and a good example of why documents are still required.
Conclusion
In the past, waterfall methodologies, quality standards (particularly CMM), and simply the influence of how things are done in other "engineering disciplines" have meant that there is far too much emphasis on documentation in the software development process. On the other hand Agile extremists have gone to the other extreme of MVD or even no documentation. The right balance is somewhere in between.
That said, it's better to err on the side of too little. But I still believe that for a large project some documentation is needed to explain or remember important details that cannot be easily gleaned from the code.
In the past, waterfall methodologies, quality standards (particularly CMM), and simply the influence of how things are done in other "engineering disciplines" have meant that there is far too much emphasis on documentation in the software development process. On the other hand Agile extremists have gone to the other extreme of MVD or even no documentation. The right balance is somewhere in between.
That said, it's better to err on the side of too little. But I still believe that for a large project some documentation is needed to explain or remember important details that cannot be easily gleaned from the code.
Some simple rules to remember are:
- avoid documentation if you can
- there are often better alternatives (like Unit Tests)
- technical documentation is written for the developers only
- practice continuous documentation - ie, update the doc at the same time as the code
- ownership of documents by the team is just as important as content
No comments:
Post a Comment