[Docs Rewrite] Discussion: Docs writing guidelines and issue templates

[markerikson]

As a preface to actually fleshing out the docs writing tasks, I've been doing research on how to actually write good documentation. I wanted to write down some notes on what I've learned, and discuss how we can help make sure that the new docs content tries to conform to those approaches.

Docs Writing Resources

I specifically recommend that people should read through What Nobody Tells You About Documentation. It's a great post that gives excellent advice about the main categories of tech docs, and the type of content that should go in each category. The HN discussion thread on this post may be useful as well.

Additional resources worth reading:

• The Four Layers to Great Documentation
• Writing Good Documentation for Your Open-Source Library
• Writing Documentation When You Aren't A Technical Writer
  • Part 1
  • Part 2
  • HN comment thread, with comments from Chrome writer Kayce Basques
• What to Write

Goals

I'd like us to have some kind of consistent set of questions that we would try to answer / use as guidelines when we work on a doc section, along the lines of:

• What content category is this page? (tutorial, how-to, explanation, reference)
• Who is the intended target audience?
• What knowledge are we assuming they should have?
• What are the intended results or takeaways from reading this page?
• What is the most critical info they should learn?

I'd actually like to somewhat codify this in the form of an issue / PR template specifically for new and updated docs content. (It might also be nice to have templates for small docs updates like typos and such.)

Questions for Discussion

• Any other good docs writing resources we should be learning from?
• Similarly, what other good docs sites can we learn from (like Vue and NgRx)? What takeaways and examples from those?
• Are those guidelines sufficient? What other things should be included?

Tasks

• Finalize docs writing guidelines
• Create new issue and PR templates for new docs content and small docs tweaks

Notes and Takeaways

Some summaries and key points from those posts:

• What nobody tells you about documentation - Blog - Divio
  • Four categories: tutorials, how-to guides, explanation, tech reference
  • Summaries:
    • Tutorials:
      • Learning-oriented
      • Allows the newcomer to get started
      • Is a lesson
    • How-to guides
      • Goal-oriented
      • Shows how to solve a specific problem
      • Is a series of steps
    • Explanation
      • Is understanding-oriented
      • Explains
      • Provides background and context
    • Reference guide
      • Information-oriented
      • Describes the machinery
      • Is accurate and complete
  • Details:
    • Tutorials:
      • Need to be meaningful, achievable, useful to a beginner, easy to follow
      • Learn by doing
      • Get the user started, even if it's not the "correct" way
      • Make sure it works
      • Ensure they see results immediately
      • Tutorial must be repeatable
      • Focus on concrete steps, not abstract concepts
      • Provide minimum necessary explanation, and focus on only steps they need now
    • How-to guides:
      • Recipes to achieve a specific end
      • Answer questions that a beginner might not formulate
      • Can assume some understanding of the basics
      • Provide a series of steps
      • Focus on results
      • Solve a specific problem
      • Don't explain concepts
      • Give some flexibility / ways to adapt
      • Leave things out - keep it practical, not complete
      • Name it well
    • Reference guides:
      • Only describe
      • Code / information oriented
      • Austere and to the point
      • Structure around the code
      • Be consistent and accurate
    • Explanation:
      • Clarify and broaden coverage of a topic
      • Provide background and context ("how X works with Y", "why a design decision", etc)
      • Discuss alternatives and opinions
      • Don't give instruction or technical reference
• Writing Good Documentation for Your Open-Source Library - Blog Brainhub.eu
  • Sections: README, Reference, Guide Cookbook, Blog post
  • README:
    • Brief sales pitch
    • What problem does your lib solve and how does it help the user?
  • Guide:
    • Helps users navigate through features
    • Start a guide page by outlining scope and establishing what prior knowledge the user should have
• Writing Documentation When You Aren't a Technical Writer | Hacker News
  • Know your audience and write for them
    • What knowledge are they bringing in (so you don't have to cover it)?
    • What knowledge are you assuming they know?
    • Given that audience, what is the most critical information they should take away?
• Writing Documentation When You Aren't A Technical Writer — Part Two | Stoplight API Corner
  • Avoid words like "easy", "simple", "trivial", and "not hard"
    • can maybe use GitHub - get-alex/alex: Catch insensitive, inconsiderate writing to help lint for those
• What to write | Jacob Kaplan-Moss
  • Tutorials
    • Be quick (new user should experience success in 30 minutes)
    • Demonstrate how the project "feels"
  • Topical guides
    • Should be comprehensive
    • Come away knowing the vast majority of possible options, and understand how concepts fit together
• Writing great documentation - Taylor Singletary - Medium
  • Highlight key points (bold, italic, underline, font size)
  • Tell stories
  • Outline and tell stories with the headlines
  • Anticipate ways a question could be asked, and route variants to a canonical FAQ answer
  • Listen to devs. Figure out what's needed in docs based on common pitfalls or misunderstandings.
• GitHub - jamiebuilds/documentation-handbook: How to write high-quality friendly documentation that people want to read.
  • Use shorter / easier words and avoid idioms
  • Link to other docs but only as reference. Inline explanations.
  • Reuse the same examples and keep expanding them.
• Dan Abramov on Twitter: "Top two mistakes in documentation: • Assuming people know everything • Assuming people are stupid"

[mkarajohn]

I have a question that I think is important, because it will help us focus:
What parts of the documentation do you think that need a rewrite? I think it's important to make the distinction between the good parts of the docs and the bad ones.

EDIT: Oh, I am blind, I just noticed ALL the other issues tagged as [Docs Rewrite].

[markerikson]

@mkarajohn : heh :) and yeah, see the notional planned outline at #3313 (comment) that I'm working from.

[markerikson]

I think I managed to add some issue and PR templates:

#3620
#3625

Thanks to @brandonroberts for the suggestion of a "landing page" PR template that points to the "real" templates

[markerikson]

Earlier I was asking what ES syntax we should use for snippets such as thunks:

https://twitter.com/acemarke/status/1196857558457290752

@alexkrolick just had a great suggestion - docs snippets should be available in multiple language versions so you can compare syntax:

https://twitter.com/TensorNo/status/1196864442262147072

Obviously that's a lot of extra work, but that part's doable. The real question is whether Docusaurus v2 supports that yet. @wgao19 , @endiliey , @yangshun : thoughts?

edit

Don't know about v1, but it looks like v2 explicitly supports this:

https://v2.docusaurus.io/docs/markdown-features#multi-language-support-code-blocks

[yangshun]

As mentioned in my tweet, Docusaurus v2 already supports code blocks for in multiple language but you have to write the different versions yourself. https://react-tracked.js.org/docs/quick-start does something similar but @dai-shi wrote his own Remark plugin to do it.

[alexkrolick]

@markerikson we are using tabs in the Testing Library query docs on v1 (syntax below), but the V2 mdx option seems good too.

• https://testing-library.com/docs/dom-testing-library/api-queries#bytitle
• https://raw.githubusercontent.com/testing-library/testing-library-docs/master/docs/dom-testing-library/api-queries.md

<!--DOCUSAURUS_CODE_TABS-->

<!--Native-->

```js
import { getByTitle } from '@testing-library/dom'

const container = document.body
const deleteElement = getByTitle(container, 'Delete')
const closeElement = getByTitle(container, 'Close')
```

<!--React-->

```js
import { render } from '@testing-library/react'

const { getByTitle } = render(<MyComponent />)
const deleteElement = getByTitle('Delete')
const closeElement = getByTitle('Close')
```

<!--Cypress-->

```js
cy.getByTitle('Delete').should('exist')
cy.getByTitle('Close').should('exist')
```

<!--END_DOCUSAURUS_CODE_TABS-->

[markerikson]

One thing I'd like us to do as part of the docs rewrite is to drop terms like "simple", "easy", and "just" from our docs entirely.

Here's an article with some details on ways to do that:

https://dev.to/meeshkan/how-to-remove-condescending-language-from-documentation-4a5p

[markerikson]

I like how the Cypress docs prefix each page with a "What You'll Learn" callout:

https://docs.cypress.io/guides/getting-started/installing-cypress.html

Example:

What you'll learn

• How to install Cypress via npm
• How to install Cypress via direct download
• How to version and run Cypress via package.json

I also see that they've got 3 or 4 different color variations on blockquotes. Their files do that with templating:

{% note success Core Concept %}
Cypress provides a simple but powerful algorithm when {% url " interacting with elements." interacting-with-elements %}
{% endnote %}

I imagine we might be able to do that with a React component that renders <blockquote className="success"> instead, and use that from MDX once we're converted to Docusaurus v2.

[markerikson]

Some good suggestions for creating short readable code samples in docs:

https://ts.chibicode.com/refactor

• Make code samples mobile-ready
• Prefer minimal code samples
• Prefer practical code examples
• Fail fast (show examples first where things don't work right)
• Use themes, analogies, and quizzes
• Add a thoughtful touch
  • Visually emphasize important parts in your code samples
  • Use mostly-text graphics
  • Avoid difficult English words/phrases
  • When you skip a step or assume prerequisite knowledge, say so
  • When things get hard, be encouraging

[markerikson]

Google just posted a set of "Technical Writing" mini-courses:

https://developers.google.com/tech-writing

[brandonroberts]

Google just posted a set of "Technical Writing" mini-courses:

https://developers.google.com/tech-writing

Nice! Definitely going to go through these

[markerikson]

The Vue docs have a great set of writing guidelines here:

https://v3.vuejs.org/guide/writing-guide.html

[markerikson]

And Digital Ocean has some excellent guidelines as well:

https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines

[evildmp]

@markerikson Hi - I'm the author of the documentation system you mention (which is now published and updated at https://diataxis.fr). I'm doing free workshops for open-source projects in the Python ecosystem, to help improve their documentation. If there's interest in the JS world, please get in touch.

[markerikson]

The Solid folks just put up a docs writing guide that looks pretty good:

https://github.com/solidjs/solid-docs-next/blob/main/WRITING.md

[hilmanski]

Thanks @markerikson for putting up this list. I'm currently exploring how to make our documentation better and this has been helpful.

Note: the link from stoplight is not valid anymore: here is the alternative:

• https://medium.com/@taylor_atx/writing-documentation-when-you-arent-a-technical-writer-part-one-ef08a09870d1
• https://medium.com/@taylor_atx/writing-documentation-when-you-arent-a-technical-writer-part-two-59997587cc2a