Why do you need a valuable system documentation ?
Table of contents
How to write valuable system documentation with agile principles ?
How can i figure out if my documentation is valuable ?
How does the structure of a good documentation looks like?
Why do you need the system-documentation in this sequence?
How can i optimize my system documentation?
Don’t i need process documentation?
How can i avoid redundant documentation?
How could we improve the quality of this article ?
Source code convention tools
Literature, good books and references
How can i subscribe/feed this blog ?
Want to stay up to date ?
How can i rate this blog ?
Where do i find more clean code knowledge and gadgets?
How to write valuable system documentation with agile principles ?
Hi there! In this blog i wanna show you, why agile concepts need a valueable documentation and why to many developers missunderstand the agile manifest. You’ll see and understand how to structure the documentation, to figure out a good, valuable documentation saving a lot of time. This blog will give you some tequiniques and methods and best practices making your company more profittable as you always has dreamed of it. Share this expirience with other developers.
How can i figure out if my documentation is valuable ?
Well, to understand that, we must find out what is essencial needed and why! To do so before writting any documentation ask yourself those valuable questions:
Document purpose : Why do i really need this documentation ?
Documentation sort : How does the minimally systematic looks like ?
If you can’t aswer those questions, do not spend a lot of time writing something that nobody will read. We only write documentation if it brings an additional benefit.
Important: If it is possible to solve or clear something over conversation, favor this way over writing documentation.
How does the structure of a good documentation looks like?
Well first of all we must know, what kind of documentation a software really needs and how to differentiate between system-documentation and stakeholder-documentation.
A system-documentation looks normally like this acc. to the best practises :
· Architecture overview (maintenance, build deployement, development)
· Interface handbook (for external partners)
· Operating handbook (for operation, installation etc.)
· Admin handbook (for context administration)
· Support handbook (after delivery and only if needed)
This was a template. To be sure you have covered the needs of your stakeholders show it to them and ask for feedbaks. It is always better to make pro-active a proposal because otherwise the stakeholders could say: i need it all or everything is nescessary.
Why do you need the system-documentation in this sequence?
Well thats a good and very important question, because here you get the reasons why it tis essencial to have it.
We can expect that the maintenance and support/service phase is avarage 3 times bigger than the construction phase. In agile contexts even much bigger because of the short delivery cycles. The system-documentation you need exactly for this phase. (For the life cycle after delivery). For this reason the system-documentation must document mainly all information you need to maintain and support the system without asking developers or getting know-how from experts, that may no longer work in the company.
Construction vs Maintenance (3-5 times bigger)
|__________|__________|__________|__________|__________|__________|
How can i optimize my system documentation?
Well the principle here is not what ist possible, but what is really nescessary. Project-documentation is not a system-documentation. Favor the direct conversation with the stakeholders and ask them what they really need and why. The system-documentation contains in most of the cases all information needed.
The only reasons to write project documentation are :
· Big projects : If the direct project communication is not possible.
· High risk : to control risks. Usually medical projects and projects for the state.
· Law requirements : the law requires it.
Don’t i need process documentation?
Good question. Sure! Process documentation is an internal and structural documentation. The most companies has it already, since they are ISO-Certified. This kind of documentation defines rules, process, concepts, models, project plan, meetings etc. If your company does not have an established process documentation you should do ti now ! Don’t think you can live without it. This is only true if your company has 3-5 employees.
How can i avoid redundant documentation?
Example : You do not have to write additional documentation if the information is normally only available for developers. Cookbooks, Source code, JavaDoc etc. describe and help developers enough. Do not spend time, documenting those things. Developers will do it automatically, if they need. Instead you should insist on a cookbook by developers. (developers should do that at a minimum to ensure know-how-transfer)
