Rules for Writing

Regardless of the type of documentation—APEX help page, developer comment, item help, spreadsheet, diagram, or formal text document—I strongly recommend the following guidelines. On purpose, these are the same suggestions for publishing individual rules and guidelines in Chapter 7. Consistency across all areas of a project is nice—it promotes predictability and comfortability and can actually be habitforming.

• Use short and concise active voice sentences.
• Write in full sentences: capitalize the first word, and place a period at the end of each sentence.
• Use clear, meaningful, full-word names for all objects.
• Use screenshots and diagrams generously.
• Consider using APEX’s websheet tools to author a web-based document.
• Ensure accuracy. Few things will discourage developers from taking advantage of good documentation so much as simple lack of accuracy.