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