How should we do Software Development Documentation ? How do we capture and document requirements, Use Cases, Software Architecture, High Level Design, Low Level Design, code and associated comments, fault reports, test plans, test cases and results. More importantly how do we keep them consistent, up to date and properly reviewed. How do we know if a requirement change has filtered down to implementation and testing. When reviewing documents how do we know what changed since we last reviewed it or tell whether the comments we made last time are reflected in the document.
In my experience we struggle to get all of this right. We know documentation is important but we also know it can be very expensive to keep it accurate. A seemingly small software change can require updates to many documents. When time is tight (which it usually is) documentation can be neglected. Also we tend to combine documents so there are less documents to maintain. Software Architecture and even High Level design can creep into Requirements related documents. High level design and low level design can also end up in the same document. Low level design can often look like code.
Lots of people have tried to solve these problems in different ways. I remember CASE (Computer Aided Software Engineering) was going to make the world a better place and maybe it has but I haven't seen it. Perhaps because the CASE tools are so expensive and its hard to do it right. Agile methodologies seem to reduce the emphasis on documentation and update it iteratively which sounds like a good thing and may be the most realistic way to go about it but must be hard for upper management and the bean counters to see what a project will cost.
So my idea is to get rid of the static linear MS Word documenta which only provides one way to look at our information and replace it with a dynamic non-linear web based repository. This is not a new idea as far as viewing information goes since we see it all the time when we access information via a browser. We select what we want to see (eg via a search term in Wikipedia) and the information is fetched, transformed and presented.
So take all the documentation, break it up into discreet chunks, define what the chunks are and how they link to each other and then serve up into whatever view is useful to the user. Even code could be integrated into this view of documentation. We would need to be able to export to PDF and probably MS Word to keep those people happy who still like to have linear documents.
Once accessible in this manner very powerful use cases become possible. For example imagine we have a number of chunks tagged as Requirements and they are linked to other chunks tagged for Design and Test Cases. Also imagine that the Requirements and Design chunk have attributes indicating version number and review dates and the Test Case chunks have attributes indicating number of outstanding defects at various levels. Now imagine a project is associated with a number of Requirements and how easy it would be to run a report of the status of the project with respect to completion and review of all required documentation artifacts as well as outstanding defects. If a Requirement is changed it would be straightforward to determine what else needed to be changed and for reviewers to be assigned and for them to only need to review the particular requirements that have changed.
With this sort of approach we can be more granular in the documentation so we could have Software Architecture, High Level Design and Low Level Design chunks that link together and are straightforward to keep consistent enabling us to produce a High Level Design document if so desired.
Literate programming becomes more viable if we can extract the documentation out of the code and view it in conjunction with the rest of the documentation. We just need to have the appropriate links from Design chunks to the code.
So what's the catch ? Integration with existing tools is key. One needs to be able to produce a good looking PDF or Word document for any required view of the documentation. This would require generating all the appropriate sections headings at the correct level and embedding pictures at appropriate places. Acrobat and MS may actually provide tools to help with this (ie construct documents using tools rather than via a user interface) but another avenue could be to generate OpenOffice documents (assuming its XML format is documented well enough) and then use its export tools to create PDF and MS Word.
One also needs to be able to import data from other tools into the documentation system and then launch the original tool when the data needs to be edited again. So for example Visio could be still used to create diagrams. Over time browser based replacements for the external tools would appear and it would become a seamless experience. One could even imagine an integration with a tool like Eclipse to have a single application for editing code and documentation (eg via an inline Browser).
No comments:
Post a Comment