On writing docs

Hello! Welcome to my place for writing docs.

My name is Qing Xiong. Here I will sum up:

• My thinking on writing docs.
• How I write docs.
• What I check for editing.

I'll only talk about how to write a doc by thinking words, sentences, paragraphs, and pages. I won't cover how to design/test docs.

This README is for you if you want to:

• Know me about writing docs.
• Get new ideas about writing docs.
• Just read.

My thinking on writing docs

We often deal with 3 major tasks in writing docs whatever industries, services or products, target audiences, and types of docs you are writing for. These tasks include:

• Telling how: to do things like how to set up an account or configure a service.
• Telling what: to give things like a concept or an idea.
• Telling why: to explain things like a concept, a process or an action.

To help users achieve what they want from docs, we need to write docs:

• User-ly: write as a user.
• Accurately: give facts and correct steps.
• Clearly: use plain language and good formats.

Write user-ly

The hardest thing in writing docs? You don't know whether you are on the same page with your users, that's, what you say is what users see. Do users get what you talk about? Will users do your steps and get the correct result? To test this, you have to switch from a writer to a user.

When explaining a concept, You have to think, "Did I understand it?". Or when giving steps, you have to ask, "Can I do it easily and correctly?". You may say, "Oh, what about the way I understand something is different from other people"? Yes, that happens, but at least you are doing things you can do for users, and it's time to gather feedback for improvement you see fit.

Here is the toolkit to write user-ly:

1. Write a user statement. You ask these questions:

   • Who are you?
   • What do you have(exp/skills)?
   • What do you want from me?
   • What can I do for you?

2. Use "you" to call users you are writing for.

3. Write like talking to people: use plain English and an informal tone if you can.

4. Avoid "please" most of the time.

5. Test while you write: Read or do things in your doc to see whether you can understand it or do it easily and correctly.

6. Do a mini user research: if not sure your writing will satisfy users, check out what users are thinking and talking about it. You can do this with approaches like searching online, asking colleagues, or diving into your team's user research reports.

Write accurately

Under the specified condition like an environment or platform, writing accurately means:

• You give facts and correct steps in docs.
• Users get info you describe with little or no misunderstanding.
• Users follow steps and get the correct result you claim.

Accuracy of docs is the most important thing in your mind as a writer. If users do actions you tell and get a different result, then your docs fail. You need to ensure the most of your docs, say 97% or higher, are correct and won't fail users to keep reading through.

Here is the toolkit to write accurately:

1. Use things you are writing for as an everyday user. If you don't love using it, it's hard to write something useful for users.
2. Test while you write.
3. Think before copying something into your docs.
4. ?

Write clearly

Writing clearly means users can get what you say without thinking three times over it.

Here is the toolkit to write clearly:

1. Use plain language. The essentials of plain language are simple, short, common, and organized wording.
2. For actions, say where to do + how +/- purpose +/- useful bonus actions.
3. Put conditions before actions.
4. For giving links, specify why users need the link + a highlight of what the link says.
5. If a term is long and appears at least 3 times, use its acronym + First time rule : use term (its acronym) for the first instance. The first instance usually ?
6. Use the same term.
7. Only use a pronoun if users don't need to think about twice what it means.
8. If this/that or their plurals can mean many things, use this/that or their plurals + the things you want to refer.
9. Use if for conditions, whether for two results possible, while for the same time, because for reasons, when for at some time, though for unfavorable conditions, but for the contrary, after for the passed time, before for the coming time, and since for the start time.
10. Don't mix up if and whether for two results possible, while and though for unfavorable conditions (avoid despite, even though, although, and even if), since and because for reasons, but and however for the contrary, after and once, and if and when for conditions.
11. If seeing two or more instances of you in a sentence, cut them as possible or use verb + object.
12. Use the present, future, and past tense as possible. Avoid other tenses as possible.
13. If something stops users keeping learning or doing, put them before the place users start reading.
14. Ensure using brevity gives users the same reading experience as the one when you give details.
15. Don't use as for anything at Bullet 9.
16. Note there is and you can.
17. Use with: for the A has B meaning, use A+ with + B ; for A do B by using C, use A + B + by using C if A do B with C may mean B has C, otherwise use A do B with C, and A + with + C if no B.
18. Use should for advice, can for ability, will for future, might for possibility, must for necessity, and may for permission.

How I write docs

?

What I check for editing

Here is a list to check for editing:

• Passive voices?
• Change nouns to verbs?
• Pronouns clear?
• Verbs not specific?
• Cut unneeded words?
• Use simple and short words/phrases?
• Long and complex sentences?
• Use the "subject + verb + object" structure?
• One subtopic for one sentence?
• Steps in ordered lists?
• One topic for a paragraph?
• Key things/sum-up first in a paragraph?
• Target users and requirements specified?
• Use lists/tables?
• Steps give claimed results?
• Spellcheck?
• Use the same terms?
• ?