How To - Writing for the Vault
Table of Contents
Give Guidance to the Reader
The readers job is to spend the MINIMUM amount of time reading your doc. They will quit if they don't find what they need in a few seconds.
Your first responsibility as the writer is to signal to them that this doc will get them the knowledge they need, and in the minimum amount of time.
The doc should give the MAXIMUM amount of value to the reader for the MINIMUM time possible..
Some ways to give guidance
The beginning of the document is where you give guidance. Some things you can state are:
The purpose of the doc
What problem does X solve?
Why is this important?
Who has this problem
Outcomes/learnings after reading the doc
KEEP IT SIMPLE, READABLE
Example: Why do we need guidance?
Yes, but what is Multi server chat??
Example: Good Guidance
The explainer here tells you why you need Otter.AI, what problem it solves, and how it solves it.
No Unfinished Work/No Drafts
If you've made a merge/pull request, the doc should be ready to publish. No drafts, no unfinished sentences, no placeholders.
You can update the doc in the future to add more things. Yet it should look and feel complete.
What can we improve?
Don't do big blocks of writing. nobody will read them.
Use BOLD to draw attention, drop spaces between lines to increase readability, use Headers to chunk up paragraphs, and rewrite sentences to become clearer, simpler.
If your doc is long, add Headers and Link to them at the beginning of the doc
Use "#" to add headers. Headers will separate the topics and make the doc more readable
At the top of the page, add links to each of your headers, so users can easily jump to what they need.
You can add header links like this: [[littlefish - Vault Guidance#Don't do big blocks of writing nobody will read them]]
Be careful with writing between texts
Such texts won't be seen, won't be read, won't be known by the user.
Last updated
