Writing Style

Forked from jupyterlab writing style and expanded with some ideas from blog articles (i.e. angel.co)

Documentation

  • The documentation should be written in the second person, referring to the reader as “you” and not using the first person plural “we”. The author of the documentation is not sitting next to the user, so using “we” can lead to frustration when things don’t work as expected.

  • Avoid words that trivialize using Plug'in such as “simply” or “just”. Tasks that developers find simple or easy may not be for users.

  • Write in the active tense, so "check the IP address with..." rather than “the IP address can be checked with..."

  • The beginning of each section should begin with a short (1-2 sentence) high-level description of the topic, feature or component.

  • Use “enable” rather than “allow” to indicate what Plug'in makes possible for users. Using “allow” connotes that we are giving them permission, whereas “enable” connotes empowerment.

  • The seven rules of technical writing:

  • Write in two steps: Focus on ideas and then on reviewing and shaping your text.
  • Target the readership: Who is going to read it?
  • Use a simple style: Keep it straight and simple. Use good grammar.
  • Limit the scope of the information: Introduce one concept at a time.
  • Use realistic code examples: "Foos" and "bars" should be avoided.
  • Use a light but sufficient approach: You are not writing a book!

  • Use templates: Help the readers to get habits.

  • Write documentation that sells. It is what will convince others that the project is worth working in.

Code

Write Code Any Engineer Can Read

Your code has to be written so it's simple for outside engineers to understand.

This means:

  • Refactoring your code to be as simple as possible
  • Following style conventions for names, whitespace, etc. (i.e. PEP8 for python)
  • Replacing private information with environment variables
  • Commenting your code to contextualize snippets within your broader codebase.

Books

There is an enormous bunch of books describing the best practices to write in each language as well as in a general manner and helping to structure your code. You are invited to read and consult them regularly.