This comment explains what I know about writing docs to make them easier to understand. A succinct paragraph at the top should state what the rest of the document will cover. Don't create a document with random "stuff" in it and not explain what that "stuff" is at the beginning.
## Header Sections
Break up your document into discrete sections. They can be categories, a series of steps, etc. These headers break up the page into logical chunks of information. The header title pre-loads your brain to receive the following information, and makes it easier to skim. These header sections become a Table of Contents later.
## Grouping Information
A leading sentence groups a set of correlated bullet points:
- bullet points are useful visual indicators
- they break up important points
- they are very easy to absorb individually
Call out the major steps needed to perform an action.
Step 1. Figure out the major parts of your instructions
Step 2. Break up instruction into discrete steps
- Provide sub-grouping for complex steps
Step 3. If additional steps are required but not included here, call out
that they are necessary and where to find further information.
## Adding Emphasis
Using specific emphasis can help to underscore __unique information__ and make it easier to find specific information ON THE PAGE. It also helps break up concepts visually, making it Easier To Read.
Emphasis makes skimming easier. Skimmability makes it more likely people will absorb the information you want them to.
## Be descriptive
Using extra, otherwise unnecessary words can "de-compress" a concept so that it takes less brain power to understand what the words mean. It may not be beautiful prose, but it will be easier to understand to more people.
Don't be afraid to break a paragraph up to make it easier to read. One idea spread over many paragraphs is a lot easier to understand than trying to pack it all into one.
## Don't make assumptions
Probably more than one person will be reading your document. We all have different life experiences and will interpret it slightly differently. Ask yourself if all your readers know everything you know. Probably not, or they wouldn't be reading your doc!
Before you dig into something complicated, think about what information is necessary to understand it. List the pre-requisite knowledge needed to grok the next information. Provide background information for concepts you haven't covered yet, and refer to other documents when possible.
## Use Graphics
Complex concepts can be understood easier when presented visually. If it would take you two pages to explain something that a simple diagram or flow chart can express, start with the visual. Use the text to explain details that the diagram doesn't show.
# Edit, edit, edit
Drafts are important. Constantly revise your document as you write it. Review it and see if re-writing or re-organizing sections makes it easier to read. Read it from the beginning and see whether your edits have stopped making sense, and edit again.
Documents get better when you revisit them later and solicit feedback. A fresh perspective is always good.
## About
This comment explains what I know about writing docs to make them easier to understand. A succinct paragraph at the top should state what the rest of the document will cover. Don't create a document with random "stuff" in it and not explain what that "stuff" is at the beginning.
## Header Sections
Break up your document into discrete sections. They can be categories, a series of steps, etc. These headers break up the page into logical chunks of information. The header title pre-loads your brain to receive the following information, and makes it easier to skim. These header sections become a Table of Contents later.
## Grouping Information
A leading sentence groups a set of correlated bullet points:
Call out the major steps needed to perform an action. ## Adding EmphasisUsing specific emphasis can help to underscore __unique information__ and make it easier to find specific information ON THE PAGE. It also helps break up concepts visually, making it Easier To Read.
Emphasis makes skimming easier. Skimmability makes it more likely people will absorb the information you want them to.
## Be descriptive
Using extra, otherwise unnecessary words can "de-compress" a concept so that it takes less brain power to understand what the words mean. It may not be beautiful prose, but it will be easier to understand to more people.
Don't be afraid to break a paragraph up to make it easier to read. One idea spread over many paragraphs is a lot easier to understand than trying to pack it all into one.
## Don't make assumptions
Probably more than one person will be reading your document. We all have different life experiences and will interpret it slightly differently. Ask yourself if all your readers know everything you know. Probably not, or they wouldn't be reading your doc!
Before you dig into something complicated, think about what information is necessary to understand it. List the pre-requisite knowledge needed to grok the next information. Provide background information for concepts you haven't covered yet, and refer to other documents when possible.
## Use Graphics
Complex concepts can be understood easier when presented visually. If it would take you two pages to explain something that a simple diagram or flow chart can express, start with the visual. Use the text to explain details that the diagram doesn't show.
# Edit, edit, edit
Drafts are important. Constantly revise your document as you write it. Review it and see if re-writing or re-organizing sections makes it easier to read. Read it from the beginning and see whether your edits have stopped making sense, and edit again.
Documents get better when you revisit them later and solicit feedback. A fresh perspective is always good.