[Translate] Lean documents

Lean DocumentationLean Documentation (original)

Posted by Tomas Björkholm on APR 09, 2015

My amateur research tells me that the three most important things to achieve greater effectiveness and superior quality are knowledge, knowledge, or knowledge. Knowledge is best obtained through communication, but only with knowledgeable people can it be effective. Unfortunately, in some cases such people are unable to participate in the discussion.

My amateur have given me the insight, the three most important things for greater effectiveness and good quali  Ty is knowledge, knowledge and knowledge. Knowledge is best acquired through a dialog but a dialog are only efficient if it includes someone with knowledge. Unfortunately, there was situations when such a was not around.

This article will help you write valid and useful documents in situations where only the documentation is the only source of knowledge. The practice described in this article is based on my experience in a project involving a large cross-company.

This article would help you write effective and useful documentation for those situations where documentation are the only a vailable source of knowledge. The practices presented in this article is based on my experiences working to a project at a big multinational company.

It all started with a developer who made an idea to improve the project documentation. We've focused on a team that is interested in improving the documentation and reaching a consensus on some principles.

It all started if a developer said he had an idea for improving the project documentation. We gathered a team of people who were interested in improving the documentation and agreed to a few rules.

principles of Good documentationThe rules for great documentation

The documentation should:

• Fast and easy to create and update. Outdated information is worse than no information.
• Easy to provide the right answer. If it is not easy to find, no one will use it.
• It is not to replace the communication between people. People and communication, heavier than process and tools, right?

The documentation should:

• Be quick and easy both to create and update. Information that was out of date can worse than no information at all.
• Easily provide correct answers. If It's not easy to find no one would use it anyway.
• Not replace human interaction. Individuals and interaction over processes and tools, right?

To implement these rules, we have put forward six practices:

To reach the goal of fulfilling the rules, we set up six practices:

Practice 1-clarifying the user of the document and the reason for using the documentPractice 1–identify your consumers and their reasons for using the documentation

Although this seems obvious, very few people would do so. For our project, our improvement team identified 4 target groups.

• Managers, they need a short summary of what we are doing.
• New developers, they need a quick introduction.
• The previous developers of the system, who had been back to the project after doing other things for several years.
• The wrong people, they help solve the problem.

While this sounds obvious, it's rarely done. For our project, we improvement team identified four target groups.

• Managers who need a short summary of the What we ' re working on.
• New developers who need a quick introduction.
• Former developers of the system who come back to the project after a few years of doing of else.
• Trouble shooters customers with their problems.

The first group of target audiences was pleasantly surprised when we asked them about their requirements for the document. First, no one has ever asked them this question before. Wow! Second, they never used the huge documentation they had. This target group only needs to answer three things. In short, the three lines can meet the needs of the document. Superfluous for both the reader and the author is wasted. Surprise you!

The first target group was pleasantly surprised when we asked them about their documentation needs. First of all, no one had ever asked them before. wow! Secondly, they never even used the massive documents that they had. This target group is only needed the answer to three things. In total, three lines of documentation is all the was needed. The rest is waste both for the reader and the writer. Omg!

Practice 2-organize like Google EarthPractice 2–structure it like Google Earth

People use documents to find answers to their hearts ' questions. The quality of the document can be measured by the time it takes to find a solution. We use Google Earth as a model.

People use documentation to find answers to the questions they has. The quality of the documentation can is measured by the time it takes to find the answers. We used Google Earth as a model.

Have you ever looked for your house on Google Earth (step down, not the search address)? How long will it take you? Maybe 30-60 seconds? Finding your house on the surface of the earth is like finding an answer in a 1.5 trillion (1.5x10^12) answer. If you look for an answer, it shouldn't take more than 60 seconds, even if your system is complex and huge.

Ever tried to find your house on Google Earth (drilling down, not searching on address)? How long does it take? Maybe to seconds? Finding your house on the surface of the Earth are like finding 1 answer among 1,5 trillion (1,5 * 1012) answers. If you're looking for a answer it shouldn ' t take more than seconds, even if your system is complex and huge.

What is this in the documentation? We use the hierarchical analogy of moving between levels in Google Earth: the height of the moon, the height of the satellite, the height of the plane, the height of the helicopter, etc. Each level has a short description, which we call the Elevator lecture (elevator pitch), with a maximum of 9 possibilities to continue to the next level.

How does this apply to documentation? We followed a hierarchy analogous to moving through the levels at Google Earth:moon level, satellite level, airplane leve L, helicopter level and so on. Each level have a short description, which we called an elevator pitch, and up to nine possibilities to continue down the N Ext level.

Remember that not all document tools are suitable for step-by-step downward browsing (drill down). A directory structure that contains a Word document may not be a good idea. Wikis that contain links to the next level are much better.

Keep in mind, not all documentation tools is well suited for a drill down approach. A directory structure with Word documents are probably not a good idea. A Wiki with links to next levels is much better.

Practice 3-Stay streamlinedPractice 3–keep It Small

We discussed the rationale behind the documentation and suggested the following principles for minimizing the documentation:

• The document should be not limited to time and space communication. This should not be a substitute for real-time communication.
• We should record the results, not the needs. This means that we update or replace the document when we publish the new feature, rather than adding the document when we get the requirement. This ensures that the document accurately responds to the current state of the system.
• The benefits of a document must outweigh the cost of creating and maintaining it. Don't waste time documenting things that have been written in code. The document should provide a large-scale overview and enough information to help readers quickly find the necessary code.

We discussed the reason for documentation and come, and the following principles to minimize the size:

• Documentation should is communication without constraints in time or location. It ' s not a replacement for communication in real time.
• We should only document results not requirements. That means we update or replace the documents if we launch new functionality instead of adding new documents when we get The requirements. This approach ensures, the documentation accurately reflects the current state of the system.
• The benefit of having documentation must is greater than the cost of creating and maintaining it. Don ' t waste time on documenting what's already written as code. The documentation should provide a big picture overview, and enough information to help the reader quickly find the necess ary code.

Keeping the right amount of documentation is a balance between being too short and useless and too long and difficult to read. If you don't use the document, you don't update it, it loses its value, and, worse, it's bad if the document is old and misleading.

Have the right amount of documentation are a balance between too short to being useful and too long to read. If you don't use it, you won't update itand then it's worthless or even worse harmful if it ' s old and mislead Ing.

Here is the advice I received from Henrik Kniberg:

• Keep as few documents as possible-but not less
• Keep the document as short as possible-but not shorter

It's so simple:-).

The advice I got from Henrik Kniberg:

• has as few documents as possible–but not fewer
• has as short documents as possible–but not shorter

It's that's easy:-).

Practice 4-text to be fascinatingPractice 4-make The text inviting to read

A large paragraph of perfunctory writing is tedious. How do you make text more pertinent?

Long, irrelevant text is boring. How can I make your text relevant?

We tried the following: we asked a potential user to ask someone with knowledge. Readers know more about what they want to know and how to organize text than experts. Experts can only guess what the reader wants to know and how it should be organized.

We tried This:we asked a potential consumer to interview someone with knowledge. The reader knows what they want to know and how to structure the text better than the expert. The expert can only guess what the reader wants to know and how it should be structured.

A typical reverse pattern is when a person leaves the company, their manager lets them use the rest of the company's time to record what they know. For most people, this is more of a punishment than a job of creating value.

A Typical anti pattern was when someone was leaving the company and their manager asks them to spend their remaining time at The company documenting everything they know. For most people, that's more than a punishment than value adding work.

Practice 5-Incorporating visual elementsPractice 5–incorporate Visuals

Although the text should be brief, the text may take longer and contain more detail as the level progresses further. What can be done here to prevent readers from losing? The way to use popular science. Rather than writing your documents like a scientific report, use a more receptive approach to popular science magazines, including a large number of visual elements and short, easy-to-read passages.

Even though the text should is short, further down in the hierarchy, on leaf level, the text might need to be longer and C Ontain more detail.  How can this is done without losing the reader? Popular Science to the rescue! Rather than writing your documentation like a scientific report, with the approachable style that Popular Science magazine Uses, with lots of visual elements and short easy to read paragraphs.

Adding visual elements can help readers of the document quickly find what they need. The reader's line of sight jumps from one picture to another, just like reading a newspaper.

Adding visuals helps your documentation consumers find what they need quickly. The reader ' s eyes would go from picture to picture just like when you read a newspaper.

Practice 6-make it easy to maintainPractice 6-make it easy to maintain

The biggest challenge in writing a good document is to keep it up to date.

The biggest challenge in writing good documentation are to keep it up to date.

This requires some discipline and a simple boy Scout rule, "Always keep the camp cleaner than you found." In the documentation, this means: If a document does not give you the information you need- update it with the correct information once it is found.

This requires some discipline and a simple boy Scout rule, "Always leave the campground cleaner than you found it." In documentation this means:if the document does not give you the information you need–update it with the correct infor Mation as soon as you had figured it out.

The possibility of keeping the document updated, decreasing as the distance between the modified place and the place where the document was written increases. The comments in the code are closer to the changes, so the document is more likely to be updated than the one in the other tool. If you use Wikis to compose documents, you can easily integrate the comments in your code.

The likelihood of maintaining up-to-date documentation decreases as the distance between what's the change and where to Docu ment increases. Comments in code is closer to the change so they is more likely to being updated than a document in another tool. If you use a wiki for your documentation you can easily integrate comments in code.

If the document is difficult to update, or cannot be updated as the problem is discovered, it is unlikely to be updated. Use a tool to update (document) easily and even synchronously. The same applies to images, so make sure to use a tool that can create and update images directly in it. Using plantuml 's MediaWiki, and using Gliffy 's confluence, is two examples.

If the documentation is difficult to update, or can ' t be updated as soon as a issue is detected, it's less likely to be u Pdated. Use a tool for easy updates or even simultaneous updates. The same goes for images so make sure to use a tool which creates and updates images directly in the tool. MediaWiki with Plantuml and confluence with Gliffy is both examples.

ResultsThe result

Our documentation system is tested when a team in another city needs to modify the code that is normally maintained by our department. A brief introduction and an e-mail with a link to the location of the document is the only communication between us, and quite unexpectedly, all the communication needed is craved. We have achieved our goal. I have a document system that is quick and easy to create and maintain, and this helps users find the answers they need.

Our documentation came to a test when a new group of people working in another city needed to change code this is usually Maintained by our department. A short introduction and an e-mail with a link to the documentation area is the only contact we had and much to our SURPR Ise that is also all this was needed. We had reached our goal. We had documentation that is quick and easy to create and maintain, and that effectively helped users find the answers th EY needed.

I hope that our principles and practices will also help you create better documentation.

I hope our Rules and practices can help you create better documentation.

Good luck!

Good luck!

Disclaimer: There is no relationship between the lean (Lean) in the title and the Toyota manufacturer. This is just the adjective lean I use (meaning: efficient, no waste).

Disclaimer:lean in the title have nothing to do with the car manufacturer Toyota. It is the adjective lean (meaning:efficient and with no wastage) I ' m referring to.

Thanks to Ellen Gottesdiener for their support and help. Thanks to Jonas Boegård, Henrik Rasmussen and Igor Soloviev for a good idea. Thanks also to Mia Starck and Yassal Sundman for their help with the text.

Thanks to Ellen Gottesdiener for hers support and help. Thanks to Jonas Boegård, Henrik Rasmussen and Igor Soloviev for all their good ideas. Thanks also to Mia Starck and Yassal Sundman for their help with the language.

Note: The "knowledge, knowledge, or knowledge" mentioned in the first paragraph refers to: domain knowledge (understanding of the business), System knowledge (understanding the domain and architecture of the system), and recent product requirements knowledge (know what we are building). The documentation methods described in this article are best suited for domain knowledge and system knowledge, and how to bridge gaps between the two.

Note:the "knowledge, knowledge and knowledge" mentioned in the first paragraph refer to:domain knowledge (Knowing the BU siness), System knowledge (knowing the domain and architecture of the system) and immediate product need knowledge (Knowle Dge about what we is building right now). The documentation methods described in this article is best suited to domain and system knowledge, and to bridging the GA P between the.

about the authorAbout the Author

Tomas Björkholm is an Agile coach and trainer at crisp company in Stockholm, Sweden. He is passionate about training teams, especially in large enterprises. His mission is to make agile methods easy to understand and adapt. Tomas wrote two books, the Swedish Agile Method Wizard, and the forthcoming "30-day Learning Kanban development".

Tomas Björkholm works as an Agile coach and trainer for Crisp in Stockholm, Sweden. He has a great passion for growing teams especially within large enterprises. His mission are to make, Agile easy to understand, and to adapt. Tomas has written-books, a guide-to-Agile in Swedish and the soon-come "Kanban development in".

Resources

1. LEAN company Internal Information explaining + case Introduction (154 pages ppt) _ Baidu Library
   Http://wenku.baidu.com/link?url= Mvr46yqcbcnaot06pkoe4mb8ruhuvcmzjvrbzaowusecoca6dygec4jt15czmbohaukolt1hepvykcs9wzlyghpncgmvx43dj3rlauq0h7q

[Translate] Lean documents