Documentation review guidelines

Comprehensiveness

• The documentation should explain the working of a feature thoroughly
• The 'why' is equally important where it's explained why would someone want to use this feature, i.e, context and use case
• Often, the paragraphs and definitions lack clarity, it should be clear and comprehensive enough for new users to understand what the feature does
• All "features" i.e., non-mandatory fields should also be explained in the documentation
• If something can be seen on the screen, its features should be documented and explained

Grammar and spellcheck

• Run the text across a grammar and spellcheck tool like Grammarly.
• Check for and correct any errors.
• Should be in English US, not UK. Set system language and Grammarly language to English US to show correct suggestions.

Sentence voice

• Should be in active voice and not passive
• Direct language works best

Screenshots/images

• All screenshots and examples should be in USD currency ($)
• Should have little padding on either side
• Screenshots should not have cut off text or elements
• Effect should same as achieved on a Macbook Air with screen resolution set at 1280x800
• Screenshots should be placed in respective appropriate folders
• Subfolders under a module for screenshots are avoided for easier upgrades and maintenance
• Check if all image URL paths in the text also have corresponding image files attached in the PR, easier way for large PRs is to pull it locally and check
• Emphasis on fields should be made with a red rectangle

Index/contents

• When a new page is added, check whether the PR also contains index listing in contents.md for the module