Here is a simple documentation strategy that emphasises minimal yet useful documentation for small to medium sized software projects. The goal is to ensure that writing the documentation is not too arduous, and that the documents are useful both during the project and after it is finished.
Traditionally, software development organisations deliver several documents, including Requirements, Functional Design and Technical Design. In this approach, each document is heavily dependent on the previous one. This means the documentation is often inconsistent. For example, if the FD needs to be revised, the TD may need updating too.
Part of this comes from the idea of forcing the customer to make all judgement calls. This can be slow. It’s better in many cases for the development team to make the call themselves, based on their understanding of customer requirements, and communicate this to the customer. The customer can then intervene if they really need to — and they won’t need to if the developers understand the actual requirements (as opposed to the documented requirements).
Here is a description of the process.
- The customer writes a Requirements document with input from the developer.
- The developer writes a Functional Specification based on the Requirements and input from the customer.
- The Requirements document is archived.
- The developer writes a Technical Design based on the Functional Specification.
- The developer writes the software based on the Functional Specification and Technical Design.
- During development, the developer updates the Technical Design and (with input from the customer) the Functional Specification.
- After development, the Functional Specification is used as a high-level reference for users and maintainers. and the Technical Design is used as a developer’s guide.
Next is a more detailed discussion of these documents.
Requirements
Requirements documentation gives a high-level view of what the project is supposed to accomplish, so can be used for time and cost estimates. Once finished, this is also used as a basis for the Functions Specification.
Requirements documentation should be written by the customer, possibly with some input from the developer. This document should be fairly short. It should not normally be updated once it has been written — once the planning has been done and the Functional Specification written and agreed, the Requirements documentation is not used any more.
Functional Specification
Functional Specification documentation shows a detailed view of what the software is supposed to do. This is its main role during development. After this, it serves as documentation for the system, useful for maintainers and even for users.
This should be detailed enough so that development could be completed based solely on the document and reasonable assumptions. But it should not include any more than this unless it is genuinely a functional requirement. For example, it should not contain implementation details — these should be in the technical documentation if anywhere. As another example, it should not normally contain detailed screen layouts, except where they really are crucial.
This documentation is normative, so it needs to be updated as requirements change during development. However, the documentation does not need to be complete, specifying everything down to the last button. This reduces the number of trivial updates to the documentation. To make this work, the developer and customer must co-operate, so the customer only pushes for changes that they really need. The developer cannot fall into the old adversarial system, saying things like “We don’t have to build that — it’s not in the spec.”
Technical Design
This is part of the software development process. As such, it should not be too detailed — low-level documentation should be included in the source code (e.g. in Javadoc documentation), where it is more useful and more likely to be kept up-to-date. Developers and maintainers use the Technical Design as a reference during development and maintenance, so it should always be kept up-to-date.
This should contain information that cannot properly go into the source code. This includes
- decisions made before coding, such as methodologies and general development and testing strategies
- specific tactics for individual modules
- coding standards
Summary
The simple documentation strategy for software projects emphasises minimal yet useful documentation for small to medium sized projects. Writing the documentation is not time-consuming, and the documents are useful both during the project and after it is finished.
I found this site very useful. Actually I am searching the preface / title pages sample pages to write a operational manual for a security passes system developed in oracle 9i with developer/2000 as front tool. can u help me?
User documentation is a big topic in itself! I’m sure there is a lot of good information out there on it. There a bit of relevant and useful info in my head too, but I don’t really have the time to write about it just now.
have any body did expense or leave management projects
u can send documentation
any c# projects examples
hi anyone could give a link to any documentation for a quiz project in visual basic .
This is really short and nice introduction to Project Documentation.
about documentation on c-language projects
for eg:patient record(with graphics)
stupids
Nice article which gives a basic overview on software projects documentation.
This is very true in small and midsize companies.
This site really give me the tactics for the documentation of software.I suggest to implement these strategies, as possible.
Hi, this is really good , something better than nothing, but doesn’t hit bulls eye.
Can anyone provide me complete documentation on IBM Mainframe /mainframe project.
Please , i am in great need.
Thanks
Nazia
This is really short and nice introduction to Project Documentation.
i need a link of example of a website using asp.net??
pls hlp:(
plese post me documentation for railway reservation system
plese post me documentation for Petrol Bunk Management System Project
please post me documentation for Petrol Bunk Management System Project with Front End:VB.NET & Back End:MS-Access
very useful site.
i need someone to provide me the documentation for a project in PHP & Mysql
this site is very useful for us
plz provid me the documentation of survey data entry software for product
we are need example of software documentation
line .net (my project is e-library for my university , i work it in visual studio 2008 ) , if you have template of who to write documentation ,
thx (bmwmmo@yahoo.com)
thanks for you documentaion
but it need the UML model and charts to represent clearly
the project az the user anderstand
again thanks