smoa/docs/standards/DOCUMENTATION_STYLE_GUIDE.md

SMOA Documentation Style Guide

Version: 1.0
Last Updated: 2024
Status: Active

---

Purpose

This style guide establishes consistent writing and formatting standards for all SMOA documentation to ensure clarity, professionalism, and usability.

---

Writing Principles

Clarity

• Use clear, concise language
• Avoid jargon unless necessary (define when used)
• Write for the target audience
• Use active voice when possible
• Be specific and concrete

Consistency

• Use consistent terminology throughout
• Follow established naming conventions
• Use consistent formatting
• Maintain consistent structure

Completeness

• Provide all necessary information
• Include examples where helpful
• Link to related documentation
• Include troubleshooting information

---

Formatting Standards

Document Structure

• Use clear headings and subheadings
• Use hierarchical heading structure (H1 → H2 → H3)
• Include table of contents for long documents
• Use consistent section ordering

Text Formatting

• Bold: Use for emphasis, key terms, UI elements
• Italic: Use for file names, code references, emphasis
• Code: Use for code snippets, commands, file paths
• Lists: Use bulleted lists for unordered items, numbered lists for procedures

Code Blocks

• Use fenced code blocks with language specification
• Include line numbers for long code blocks
• Add comments to explain complex code
• Keep code blocks focused and relevant

Tables

• Use tables for structured data
• Include headers
• Align columns appropriately
• Keep tables readable

Diagrams

• Use consistent diagramming tools (PlantUML, Mermaid, Draw.io)
• Include captions
• Reference diagrams in text
• Keep diagrams simple and clear

---

Terminology

Standard Terms

• SMOA: Secure Mobile Operations Application (use full name on first reference)
• MFA: Multi-Factor Authentication (use full name on first reference)
• RBAC: Role-Based Access Control (use full name on first reference)
• API: Application Programming Interface (use full name on first reference)

Naming Conventions

• Modules: Use format core:module-name or modules:module-name
• Files: Use kebab-case (e.g., user-manual.md)
• Code References: Use backticks for inline code
• UI Elements: Use bold for UI element names

Acronyms and Abbreviations

• Spell out acronyms on first use
• Use consistent abbreviations
• Maintain acronym glossary

---

Document Types

Technical Documentation

• Focus on technical accuracy
• Include code examples
• Document APIs comprehensively
• Include architecture diagrams

User Documentation

• Use simple, clear language
• Include step-by-step procedures
• Use screenshots liberally
• Focus on tasks and outcomes

Administrator Documentation

• Include configuration details
• Document all parameters
• Include troubleshooting sections
• Provide security considerations

Status Reports

• Use consistent metrics
• Include visual indicators (✅, ⚠️, ❌)
• Be concise but complete
• Focus on actionable information

---

Language and Tone

Tone

• Professional but approachable
• Clear and direct
• Helpful and supportive
• Consistent across documents

Voice

• Prefer active voice
• Use second person (you) for user documentation
• Use third person for technical documentation
• Be consistent within each document

Grammar and Spelling

• Use American English spelling
• Follow standard grammar rules
• Use consistent punctuation
• Proofread before publishing

---

Examples and Screenshots

Code Examples

• Include complete, working examples
• Add comments to explain complex parts
• Show expected output
• Include error handling

Screenshots

• Use high-quality screenshots
• Highlight relevant areas
• Include captions
• Keep file sizes reasonable
• Use consistent naming (e.g., screenshot-module-feature.png)

---

Version Control

Document Versioning

• Include version number in document header
• Update version with significant changes
• Maintain change history
• Archive old versions

Change Tracking

• Document significant changes
• Include change dates
• Note who made changes
• Link to related changes

---

Review and Approval

Review Process

1. Author creates/updates document
2. Technical review by subject matter expert
3. Quality review by technical writer
4. Approval by appropriate authority
5. Publication

Approval Authority

• Technical Documentation: Technical Lead
• User Documentation: Product Owner
• Security Documentation: Security Officer
• Status Reports: Project Manager

---

Tools and Resources

Recommended Tools

• Markdown Editors: VS Code, Typora, Mark Text
• Diagramming: PlantUML, Mermaid, Draw.io
• PDF Generation: Pandoc, LaTeX
• Spell Check: Built-in or Grammarly

Resources

• Terminology Glossary: See TERMINOLOGY_GLOSSARY.md
• Diagram Standards: See DIAGRAM_STANDARDS.md
• Review Checklist: See DOCUMENTATION_REVIEW_CHECKLIST.md

---

Checklist

Before publishing any documentation:

• Follows style guide
• Uses consistent terminology
• Includes all required sections
• Code examples are complete and tested
• Screenshots are clear and relevant
• Links are valid
• Reviewed by subject matter expert
• Reviewed by technical writer
• Approved by appropriate authority
• Version number updated
• Change history updated

---

Document Owner: Documentation Lead
Last Reviewed: 2024
Next Review: Quarterly