# How To - Writing for the Vault ### Table of Contents 1. [#give-guidance-to-the-reader](#give-guidance-to-the-reader "mention") 2. [#no-unfinished-work-no-drafts](#no-unfinished-work-no-drafts "mention") 3. [#dont-do-big-blocks-of-writing.-nobody-will-read-them.](#dont-do-big-blocks-of-writing.-nobody-will-read-them. "mention") 4. [#if-your-doc-is-long-add-headers-and-link-to-them-at-the-beginning-of-the-doc](#if-your-doc-is-long-add-headers-and-link-to-them-at-the-beginning-of-the-doc "mention") 5. [#be-careful-with-writing-between-texts](#be-careful-with-writing-between-texts "mention") ### 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.