Documentation - Why?

M2. Maintenance typically consumes about 40 to 80 percent (60 percent average) of software costs. Therefore, it is probably the most important life cycle phase. … M5. Most software development tasks and software maintenance tasks are the same—except for the additional maintenance task of “understanding the existing product.”” This task is the dominant maintenance activity, consuming roughly 30 percent of maintenance time. So, you could claim that maintenance is more difficult than development.

Robert L. Glass “Frequently Forgotten Fundamental Facts about Software Engineering” http://www.eng.auburn.edu/~kchang/comp6710/readings/Forgotten_Fundamentals_IEEE_Software_May_2001.pdf

That is, you likely want to make it cheap to understand your system by writing good documentation.

For the same reason, you want to write good, i.e., correct and up-to-date documentation, as “Bad documentation is worse than no documentation.”, see Mikey Ariel https://www.youtube.com/watch?v=FopnpwK6ALw&list=PL8uoeex94UhGGUH0mFb-StlZ1WYGWiJfP&index=106 at 10:35.

Your turn!

Leaf through the following documentation on three popular bug- or issue- tracking systems.

Have a closer look to the installation and administration documentation.

http://www.techrepublic.com/blog/10-things/10-things-you-can-do-to-create-better-documentation/

Handover Documentation

We are focusing on technical documentation. That is, documentation written for other technology savvy people, such as maintainers or operators responsible for running and operating your system or for developers that might want to contribute to your work.

It is important that you think about who is the audience you are writing to. As said, in this semester it is technology savvy people. However, there are many different kinds of people who might want to read your documentation and you have to adjust your writing style as well as the level of technical detail to them accordingly.

Typical target groups might be:

As you can see theses groups have different backgrounds. More importantly, they have different roles in society. If you want to transport a message to your target group you have to try to talk their language.

Handover Documentation in General

You write handover documentation when you are done with a piece of work and you want to enable others to take over and to continue from where you stopped.

In general that matters when you switch to another project or job and you want to assure that your work was not for nothing.

Emma Cragg describes in her blog:

For specific pieces of work:

And more generally:

http://digitalist.ekcragg.co.uk/2013/12/10/the-art-of-writing-handover-notes/

Technical Handover Documentation, the Wisdom of the Community.

However, we have to write technical handover documentation. That is, documentation that allows others to operate our systems, report issues, react on errors, etc.

There does not seem to be any proper template for this kind of information. But various others in your situation were looking for it and got advice along the lines of:

https://stackoverflow.com/questions/217185/software-system-handover-template-are-there-any-good-examples-out-there

Having been on both sides of this process professionally, I can say that the following should be mandatory:

https://stackoverflow.com/questions/205374/what-are-the-core-elements-to-include-in-support-documentation

In the past, I’ve done:

https://stackoverflow.com/questions/927508/whats-the-best-way-to-hand-over-code-that-you-were-the-sole-owner-of-when-leavin

Technical Handover Documentation, LSD Style.

Condensing all the above to our school scenario, you want to document for sure:

Docu DevOps

Treat your documentation like code.

Technologies for Writing Documentation

More References