How To - Writing for the Vault

Table of Contents

1. Give Guidance to the Reader

2. No Unfinished Work/No Drafts

3. How To - Writing for the Vault

4. If your doc is long, add Headers and Link to them at the beginning of the doc

5. Be careful with writing between texts

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.