Best Practices

• Adhere to the document structure and style guide.

• Use Markdown as much as possible as opposed to using HTML.

• StackEdit is an in-browser editor for creating Markdown files. It allows you to save the file in the Google Drive so you can collaborate, add comments, and publish directly to GitHub.

• Grammarly is an in-browser grammar/spelling checker that helps you spot errors as you type.

• Titles for documents should focus more on the functionality rather than the technology used to implement it.

  • Example:
    • Not that great - Integrating WSO2 API-M with 42Crunch
    • Good - Securing APIs by Auditing API Definitions

• Avoid using “Please” in instructions.

  • Example: * “Please click settings ”. Instead use “Click settings”.

• Avoid cluttering the page with a lot of notes/warning/tips/info

• Add redirect rules whenever the document location changes.

• Follow the guidelines for diagrams when including a diagram to the documentation. https://docs.google.com/presentation/d/1TXASCw_ewSfgouN9jDwU_0BT6eB46l2wdaoaqilajNs/edit#slide=id.g5a7d7d2c6d_0_260 Add a note on the corresponding WUM update when a change to the document is introduced via a WUM update.

• Use bold text for the action. For e.g. Click Save.

• Move existing images to the new folder structure.