Honor only exists if it is bestowed by a group onto an individual. By joining a specific group, the group grants a person a set amount of honor. By virtue of admitting a new member into the group, the group recognizes the capacity to act with honor within the individual, which befits membership into their ranks. While being honorable or acting with honor is something we do as individuals, that code of honor is defined and accepted by others. Honor, therefore, is a social agreement about how to act within a given group or as a member of a specific society or culture.
Read MoreWhat is the right level of documentation?
I am often asked how much system documentation is necessary for a given system. And what does that documentation look like. The answer to that question is always, "It depends."
Before I give an overview of what I believe documentation should be, here are a few rules I try to live by when creating system documentation for my clients:
- Keep it simple.
- Make it usable.
Keep it simple
Sounds easy, but this step quickly spirals out of control. People often start off simple, but then add content because reasons. Yes, scope creep happens in documentation. It's caused because in this phase nobody understands what the objective is. Which leads me to my next point.
Make it usable
Documentation is a tool. You need to be able to use it. If you can't use it, it will never be used. By anyone. Ever. Documentation should be a place people go to answer questions. That's it. Questions people ask of systems include:
- What does the system do?
- Who owns the system?
- What is the system life cycle?
- When was it implemented?
- Who developed the system?
- What other systems does it interface with?
- What are its dependencies?
- Who depends on the system?
- Who are the stakeholders?
- Where does it reside?
- Why was it implemented?
- How do you use the system?
Make sure your document answers these questions and your document is on the road to usability. There are 12 questions. Your documentation should be kept to 50 pages or less. One question that isn't included is: "What are the requirements?" You can also include: "What was the testing/validation outcome?" The requirements question can be very lengthy, depending on the system, so this should be a separate document, but reference it in the core documentation. The testing/validation outcome should be a single page. Anything more than that and you've written too much.
Here's the other thing about creating usable documentation. Avoid blocks of text whenever possible. Why write a paragraph when a single sentence will do? Why write a single sentence when a diagram is so much more useful? Usability is what we want, so always opt for diagrams with simple explanations whenever possible. The best documentation will consist of nothing but a glossary of terms and diagrams.