Product Documentation Writing Guidelines

Practical guidelines for writing clear product docs: tone, screenshots, structure, and formatting conventions.

Mar 14, 2024 · 1 min read · 140 Words · -Views -Comments · Digital Life
🇨🇳 阅读中文版
Read with AI

Choose an AI assistant

ChatGPT Open in a new tab with the article link and prompt
Claude Copy the prompt, then open Claude

Open Claude
Trouble reading the article?

If the prompt is missing, copy the full prompt below into your AI assistant. If the AI cannot read the article, paste the visible passage you want to discuss and add your question.

Beyond in‑product help, we publish standalone product docs. Here are conventions I learned while writing docs at my company.

  1. Use respectful “您” rather than “你”.

  2. Avoid arrows in screenshots; mosaics and red highlight boxes are fine.

  3. Include static images and animated GIFs where helpful.

  4. External links are okay.

  5. End sentences with periods, including bullet items.

  6. Start each document with a brief overview.

  7. Steps should begin after login and include the full path to the feature, not just a partial step.

  8. In Chinese docs, add spaces around embedded English words.

  9. Bold action nouns (menu items, buttons) to highlight them.

  10. Use full‑width punctuation (colons, parentheses) for Chinese; half‑width for English.

Authors
Developer, digital product enthusiast, tinkerer, sharer, open source lover