When writing technical documentation, you should be clear and concise. Here are some helpful tips to write your docs:
- Use active voice. Emphasize the subject that is acting, rather than the action they are taking.
- DO: The product handles all billing for users.
- DON'T: All billings for users are handled by the product.
- Be specific.
- DO: Run a linter to verify there are no bugs.
- DON'T: Check to see if there are bugs by running the debugging linter.
- Remove adverbs.
- DO: Do not change the name of this class.
- DON'T: It's likely that changing the name of this class will break your code.
- Don't repeat yourself.
- DO: For additional help, contact customer support.
- DON'T: If you have a problem that cannot be solved with documentation, you can contact our customer support.
- Remove filler words. For example: "basically," "rather," "just," "as a matter of fact," "at all times."
- DO: Edit the content directly in your WYSIWYG.
- DON'T: Actually, it's best that you just edit the content in the WYSIWYG.
- Remove double subjects.
- DO: This line of CSS defines how to style a title element.
- DON'T: This line of CSS is the line which defines how to style a title element.