229 lines
5.5 KiB
Markdown
229 lines
5.5 KiB
Markdown
# 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
|
|
|