Not a suggestion for eliminating the process of documenting a software application, but rather a proposed for replacement of the documenting activity and manually produced documents with something more manageable and less likely to frighten the development team.
Initiative for this work comes from a number of discussions I have been following and also an expansion of ideas I have recently documented about best practices for software development.
1.1 Introduction
Developers nightmare – you have spent endless sleepless nights thinking about finally getting your software ready for deployment. It compiles and runs without error. It has been tested and passed user acceptance testing. It is finally ready to be released .. but, you are told that it may not be deployed until the documentation has been approved.
You have been neglecting those 200 page templates that have lying in your inbox while getting your software to compile. Now you have to spend another umpteen nights in the office writing about what it is that you have produced – yawn!
This is not a task that is going to enthuse you to do a quality job. You will probably do your best to get the documents approved asap .. anything to get your code deployed so that you can spend some quality time with family and friends.
Is this a situation you have found yourself in? I have. When I was younger, I quickly learned that this is the downside to the job of being a software developer.
Supposing though, that all you needed to do to get your software deployed, after it was already ‘working’, is to check that everything is up-to-date and consistent, post your deliverables to a ‘release’ area and organize a review meeting, with follow-up!
The following is not meant to be a complete solution, but some ideas for eliminating that boring ‘produce documentation’ task, that always seems to follow any software development effort, not only for programmers, but any member of a development team effort, including analysts, architects, testers, UI designers and any other role that produces work that needs approval.
1.2 What
Instead of identifying a document for delivery as part of a software effort, I propose to break the document into 2 components:
· the document template, and
· document contents.
Where a document has previously been identified as a deliverable, identify the document template as a deliverable. In many cases this allows for several previously deliverable documents to be replaced with a single deliverable – the template that is subsequently populated with the document contents.
This leads to 3 major activities:
· creation and management of document templates,
· production of the contents populating the template(s),
· compilation of the document from its template and contents.
1.3 How
1. Identify the stakeholders that require information that is not part of the compilable software.
2. For each stakeholder, list the information that they require in order to approve the product.
3. Work with each stakeholder to create (or select from a library) the format for a template that is an acceptable method of presenting the required information.
4. Identify dates for the delivery(s) of each template and its needed contents, and track the progress of each.
1.4 Process
For each task under How consider something along the lines of the following activities.
1.4.1 Identify Stakeholders
Stakeholders are anyone within or outside of the development team with an interest in the progress of the product. Anyone not requiring information from the product development effort, is probably not a stakeholder. Typical examples are:
· End users – who would like to see early examples of the user interface and a description of how it operates.
· Project managers – who want to be able to track the progress and effort of everything in the product repository.
· Testers – who will need to be able to access the product requirements in order to maintain test cases.
· Business owners – who will want to k now the scope of the product releases and which requirements are going to be satisfied at each release.
1.4.2 List Information
In the past when each stakeholder has been asked for their needs, they would typically turn to an existing document for reference. This document is often stripped of its current contents and has its contents replaced with information for the new product, without consideration for whether the information is ‘really’ required.
Instead, try starting with traditional document templates and work with the stakeholder to:
1. identify which sections they ‘really’ need,
2. describe the reason for this need,
3. write a description of what is documented in order to satisfy this need,
4. identify a product development timeframe for this information to be available.
Each item of information is given a location in the product repository, and duplicate information is consolidated.
Create a public interface location that always contains the latest version of each piece of information. This is the ‘release’ area.
1.4.3 Accessing Information and Publishing Documents
In many cases a stakeholder may not even require that information is presented in a traditional document form. If the stakeholder is comfortable with the repository used to contain the information, all they may need is easy access to that information.
Using a document sharing tool, such as SharePoint or a Wiki, it is relatively easy to create customized user pages that accesses only the information the stakeholder needs in a layout that makes it easy to access that information.
Alternatively, a scripted documentation tool, such as SoDA, may be used to parse a template and automatically populate it with information from the repository. Give the ability to produce the document to the stakeholder, and the development team need not be concerned with producing documents. They simply inform the stakeholders that a new version is ready for review, publish the information to the release location that the script accesses, and the stakeholder can run the script to extract the required information whenever it is convenient for them.
1.4.4 Delivery Dates And Tracking Progress
Attributes may be added to each repository element for delivery dates, assigned responsibility, progress, stakeholder(s) and a description of its contents. A reusable placeholder is created for each delivery type containing default information for each attribute.
1.5 Conclusion
As stated, the idea is not necessarily to remove documentation from the project, but to reduce the usage of the word on a development effort, and put emphasis on the ‘required’ contents and less on the document itself.
Advantages of this type of approach might be:
· The removal of unwanted/unused documentation.
· Tracking by more manageable chunks.
· Elimination of duplicate information.
· Removal of confusion over what is ‘most current’, since there is a single delivery area for every unique deliverable.
· An end to the developers nightmare of having to produce reams of documentation, after the ‘fun’ part is over.
I recognize that not all deliverable documents can necessarily be replaced in this manner. But maybe it is a start towards removing the dreaded word ‘documentation’ from a project’s deliverables list and maybe a compromise between agile proponents of minimizing documentation and those requiring documentation according to some sort of standard.
1.6 References
Links to articles that inspired this work.
Create a product information repository that contains everything that is going to be shared amongst product stakeholders. Using this repository: