Document Standards & Conventions

iSu Technologies Documentation Guidelines

Last Updated: November 8, 2025 Version: 1.0 Status: Active - All team members must follow

🎯 Purpose

This document defines standards for creating, naming, organizing, and maintaining documents across iSu Technologies. Following these conventions ensures consistency, discoverability, and quality across our entire document library.

📂 File Naming Conventions

General Rules

✅ DO:

Use lowercase letters only
Use hyphens (-) to separate words
Be descriptive but concise
Include dates for time-sensitive documents (YYYY-MM-DD format)
Use consistent terminology

❌ DON’T:

Use spaces (use hyphens instead)
Use underscores (use hyphens instead)
Use special characters (!@#$%^&*()+=[]{}|;:’”<>?,/)
Use camelCase or PascalCase
Make names too long (>50 characters)

Naming Patterns by Document Type

1. Dated Documents (emails, meeting notes, reports)

Format: YYYY-MM-DD-descriptive-name.md

Examples:

✅ 2025-11-08-mgslg-presentation-followup.md
✅ 2025-11-15-team-meeting-notes.md
✅ 2025-10-03-mgslg-demo-presentation.md

❌ 08-11-2025-mgslg-followup.md (wrong date format)
❌ mgslg_followup.md (no date, uses underscores)
❌ MGSLG Followup Email.md (capitals, spaces)

Why: Chronological sorting, easy to find by date

2. Client/Project Documents (proposals, business cases, contracts)

Format: client-name-document-type-vX.md or client-name-document-type.md

Examples:

✅ mgslg-business-case-v2.md
✅ sace-opportunity-assessment.md
✅ acme-university-proposal-v1.md
✅ etdp-seta-partnership-agreement.md

❌ BusinessCase_MGSLG.md (capitals, underscores)
❌ proposal-for-acme-university.md (too wordy)
❌ acme_proposal_final_FINAL_v3.md (inconsistent, "final" syndrome)

Why: Easy client/project filtering, clear document type

3. Templates (reusable documents)

Format: document-type-template.md

Examples:

✅ proposal-template.md
✅ business-case-template.md
✅ meeting-notes-template.md
✅ project-charter-template.md

❌ template-proposal.md (backwards)
❌ ProposalTemplate.md (capitals)
❌ proposal_template_v1.md (underscores, unnecessary version)

Why: Groups all templates together, clear purpose

4. General/Reference Documents (guides, policies, indexes)

Format: descriptive-name.md

Examples:

✅ email-templates-cheat-sheet.md
✅ master-index.md
✅ getting-started.md
✅ document-standards.md

❌ CHEAT_SHEET_EMAIL.md (capitals, underscores)
❌ cheatsheet.md (not descriptive enough)
❌ email_templates_cheat_sheet_v1.md (underscores, unnecessary version)

Why: Descriptive, discoverable, consistent

5. Case Studies & Reports (knowledge base, analysis)

Format: client-name-case-study.md or topic-analysis-YYYY-MM.md

Examples:

✅ mgslg-analytics-platform-case-study.md
✅ sace-provider-intelligence-case-study.md
✅ education-sector-market-analysis-2025-11.md
✅ seta-landscape-research-2025-q4.md

❌ CaseStudy_MGSLG_2025.md (capitals, underscores)
❌ case-study-for-mgslg-november-2025.md (too wordy)

Why: Easy filtering by client/topic, chronological organization

📁 Folder Structure Standards

Folder Naming Rules

✅ DO:

Use lowercase
Use hyphens for multi-word folders
Keep names short (1-3 words ideal)
Use plural for collection folders (proposals/, templates/)
Number folders if sequence matters (01-, 02-)

❌ DON’T:

Use spaces or underscores
Use overly long folder names
Create deeply nested structures (>4 levels)
Create redundant hierarchies

Standard Folder Structure

/category/                      # Main category (lowercase, plural)
├── README.md                  # Category overview (required)
├── subcategory-1/             # Subcategory (lowercase, hyphens)
│   ├── file-1.md
│   └── file-2.md
└── subcategory-2/
    ├── file-3.md
    └── file-4.md

Examples:

✅ /business-development/proposals/
✅ /projects/active/mgslg/
✅ /knowledge-base/case-studies/
✅ /templates/business-development/

❌ /BusinessDevelopment/Proposals/ (capitals)
❌ /business_development/proposals/ (underscores)
❌ /BD/props/ (abbreviations)
❌ /business-development/proposals/2025/november/week-1/ (too nested)

Required Files in Each Category

Every main category folder MUST contain:

✅ README.md - Category overview and navigation
✅ .gitkeep (if folder initially empty) - Ensures Git tracks empty folders

README.md should include:

Category purpose
What’s contained
How to use
Key documents
Quick links
Naming conventions for that category

📊 Document Metadata Requirements

Standard Metadata Header

Every document MUST start with YAML frontmatter metadata:

---
title: [Full Document Title]
type: [Document Type]
category: [Main Category]
version: X.Y
created: YYYY-MM-DD
updated: YYYY-MM-DD
author: [Author Name]
status: [Document Status]
tags: [tag1, tag2, tag3]
---

Metadata Field Definitions

Field	Required	Format	Example	Notes
title	✅ Yes	String	`MGSLG Business Case`	Full, human-readable title
type	✅ Yes	Enum	`Proposal`, `Template`, `Guide`, `Policy`	See type list below
category	✅ Yes	Enum	`Business Development`	Main category folder
version	✅ Yes	X.Y	`1.0`, `2.3`	See versioning rules
created	✅ Yes	YYYY-MM-DD	`2025-11-08`	Date first created
updated	✅ Yes	YYYY-MM-DD	`2025-11-15`	Date last modified
author	✅ Yes	String	`John Doe`	Primary author
status	✅ Yes	Enum	`Draft`, `Approved`	See status list below
tags	⚠️ Optional	Array	`[mgslg, analytics, ngo]`	Searchable keywords
client	⚠️ Optional	String	`MGSLG`	For client-specific docs
project	⚠️ Optional	String	`MGSLG Analytics Platform`	For project docs
access	⚠️ Optional	Enum	`Public`, `Internal`, `Restricted`	Access level (Phase 2)

Document Type Values (use exactly as shown)

Type	Use For
`Proposal`	Client proposals, service offerings
`Business Case`	Investment justifications, ROI analysis
`RFP Response`	Responses to RFPs, RFIs, EOIs
`Template`	Reusable document templates
`Guide`	How-to guides, onboarding docs
`Policy`	Company policies, governance
`Procedure`	Standard operating procedures
`Case Study`	Client success stories
`Report`	Analysis, research, findings
`Meeting Notes`	Meeting records, minutes
`Presentation`	Pitch decks, demos, training
`Contract`	Agreements, legal documents
`Email Template`	Email communication templates
`Other`	Use sparingly, be specific in title

Status Values (document lifecycle)

Status	Meaning	Who Can Edit
`Draft`	Work in progress, not finalized	Author only
`Review`	Ready for review, awaiting feedback	Reviewers + Author
`Approved`	Finalized, approved for use	Requires process to edit
`Active`	Currently in use, live document	Document owner
`Archived`	Historical reference, not active	No edits (read-only)
`Deprecated`	Replaced by newer version	No edits (read-only)

Example: Complete Metadata Header

---
title: MGSLG Analytics Platform Business Case
type: Business Case
category: Business Development
version: 2.1
created: 2025-09-15
updated: 2025-11-08
author: iSu Technologies Team
status: Approved
tags: [mgslg, analytics, ngo, business-case, roi]
client: MGSLG
project: MGSLG Analytics Platform
access: Internal
---

# MGSLG Analytics Platform Business Case

[Document content begins here...]

🔄 Version Control Standards

Version Numbering: X.Y Format

MAJOR.MINOR
  |     |
  |     └─ Minor updates, additions, corrections
  └─────── Major revisions, restructures

When to Increment Version

Change Type	Action	Example
Typo/grammar fix	Update `updated` date only, no version change	v1.2 → v1.2 (just new date)
Small addition	Increment MINOR version	v1.2 → v1.3
New section added	Increment MINOR version	v1.3 → v1.4
Content update	Increment MINOR version	v1.4 → v1.5
Major restructure	Increment MAJOR version	v1.5 → v2.0
Purpose change	Increment MAJOR version	v2.0 → v3.0
Complete rewrite	Increment MAJOR version	v3.0 → v4.0

Version History Section (optional but recommended)

For important documents, include version history at bottom:

## Version History

| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 1.0 | 2025-09-15 | Initial business case created | John Doe |
| 1.1 | 2025-09-20 | Added ROI calculations | Jane Smith |
| 1.2 | 2025-10-01 | Updated metrics with Q3 data | John Doe |
| 2.0 | 2025-11-08 | Major restructure, added Phase 2 analysis | Team |

File Versioning in File Name (when needed)

For critical documents where you need to keep old versions:

mgslg-business-case-v1.md
mgslg-business-case-v2.md
mgslg-business-case-v3.md (current version)

Best practice: Only use file name versioning for major revisions (v1, v2, v3). Don’t create:

❌ mgslg-business-case-v1.1.md
❌ mgslg-business-case-v1.2.md
❌ mgslg-business-case-final.md
❌ mgslg-business-case-final-FINAL-v2.md

Use Git for detailed version history instead.

📅 Document Lifecycle

Standard Document Lifecycle

1. DRAFT → 2. REVIEW → 3. APPROVED → 4. ACTIVE → 5. ARCHIVED/DEPRECATED

Lifecycle Stage Details

1. Draft

Purpose: Document being created
Status: Draft
Who edits: Author only
Location: Author’s working folder or shared draft folder
Review frequency: N/A (work in progress)

2. Review

Purpose: Document ready for team/stakeholder review
Status: Review
Who edits: Reviewers provide feedback, author makes changes
Location: Shared review folder or collaboration tool
Review frequency: As needed during review period

3. Approved

Purpose: Document finalized and approved for use
Status: Approved
Who edits: Requires approval process to edit
Location: Final destination in appropriate category folder
Review frequency: Annually or per schedule

4. Active

Purpose: Living document actively in use
Status: Active
Who edits: Document owner (with change tracking)
Location: Appropriate category folder
Review frequency: Quarterly or semi-annually

5. Archived

Purpose: Historical reference, no longer active
Status: Archived
Who edits: Read-only (no edits)
Location: /archived/ subfolder in category
Review frequency: None (static reference)

6. Deprecated

Purpose: Replaced by newer version
Status: Deprecated
Who edits: Read-only (no edits)
Location: Same folder with status indicator, or /deprecated/ subfolder
Review frequency: None (superseded)

Document Review Schedule

Document Type	Review Frequency	Owner
Templates	Annually or when process changes	Category owner
Policies	Annually or per compliance requirements	Operations lead
Procedures	Semi-annually or when process changes	Operations lead
Business Cases	Post-project completion	BD lead
Proposals	After client decision	BD lead
Case Studies	When significant new results available	Marketing lead
Market Research	Quarterly	BD/Marketing lead
Meeting Notes	N/A (static record)	Meeting facilitator

🎨 Formatting Standards

Markdown Structure

All documents should use consistent Markdown structure:

---
[Metadata header]
---

# Document Title (H1 - only one per document)

## Section 1 (H2 - main sections)

Content here...

### Subsection 1.1 (H3 - subsections)

Content here...

#### Detail 1.1.1 (H4 - detailed points)

Content here...

## Section 2

Content here...

---

## Version History (if applicable)

---

*Footer with document owner and last updated date*

Heading Hierarchy Rules

✅ Use ONE # (H1) heading - the document title
✅ Use ## (H2) for main sections
✅ Use ### (H3) for subsections
✅ Use #### (H4) for detailed points
✅ Don’t skip levels (don’t go from H2 to H4)
❌ Don’t use more than 4 heading levels (H1-H4 max)

Lists and Tables

Unordered Lists:

- First item
- Second item
  - Nested item (2 spaces indent)
  - Another nested item
- Third item

Ordered Lists:

1. First step
2. Second step
   a. Sub-step (or use letters)
   b. Another sub-step
3. Third step

Tables:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

Emphasis and Formatting

Bold: **important text** for emphasis
Italic: *italicized text* for subtle emphasis or terms
Code: `inline code` for commands, file names, code snippets
Links: [link text](url) for hyperlinks
Images: ![alt text](image-url) for images

Code Blocks

Use fenced code blocks with language identifier:

```python
def hello_world():
    print("Hello, World!")
```

```bash
git add .
git commit -m "Update documentation"
```

```markdown
# Example markdown
This is an example.
```

Callouts and Alerts (using blockquotes + emoji)

> 💡 **Tip:** This is a helpful tip for users.

> ⚠️ **Warning:** This is important cautionary information.

> ✅ **Best Practice:** This is a recommended approach.

> ❌ **Avoid:** This is something to avoid.

> 📝 **Note:** Additional context or information.

✅ Quality Checklist

Before Saving Any Document

Use this checklist to ensure quality:

Content Quality

Purpose of document is clear
Target audience identified
Information is accurate and up-to-date
Grammar and spelling checked
Tone appropriate for audience
All claims supported with evidence/data
Examples provided where helpful

Structure Quality

Metadata header complete and accurate
Document title clear and descriptive
Logical section organization
Heading hierarchy correct (H1 → H2 → H3 → H4)
Table of contents (if document >1000 words)
Version history (if important document)

Standards Compliance

File name follows naming convention
Saved in correct category folder
Metadata fields all filled in
Version number correct
Status appropriate for document state
Tags added for discoverability

Usability

Can be understood by target audience
Links work (no broken links)
Placeholder values replaced (no [PLACEHOLDER] remaining)
Images display correctly (if applicable)
Related documents linked
Contact/owner information provided

📝 Document Templates

Required Elements in All Templates

Every template MUST include:

Metadata section with all required fields
Purpose statement - When to use this template
Instructions - How to use and customize
Placeholder indicators - Clear [PLACEHOLDER] markers
Structure/outline - Complete document structure
Examples - Sample content showing what “good” looks like
Checklist - Pre-submission quality check
Version history table - For tracking template evolution

Placeholder Format

Use consistent placeholder format:

✅ Correct format:
[CLIENT_NAME]
[PROJECT_DESCRIPTION]
[ROI_PERCENTAGE]
[YYYY-MM-DD]

❌ Incorrect format:
<CLIENT_NAME>
{CLIENT_NAME}
CLIENT_NAME
[ClientName]
[client name]

Rules:

Use square brackets []
ALL CAPS
Underscores for multi-word placeholders
Descriptive names

🔐 Access Control & Security (Phase 2)

Access Levels

Level	Definition	Examples
Public	Anyone can view	Marketing materials, public case studies
Internal	All team members	Templates, general procedures
Restricted	Leadership only	Financial reports, confidential contracts
Project-Specific	Project team + leadership	Client project docs (during active project)

Implementation: Phase 2 (when docs.isutech.co.za launches)

Sensitive Information Guidelines

❌ NEVER include in documents:

Passwords or API keys
Personal identification numbers
Confidential financial details (unless properly secured)
Client proprietary information without permission
Unencrypted sensitive data

✅ Instead:

Reference secure password manager
Link to secure credential storage
Use [CONFIDENTIAL - See secure storage] placeholders
Mark document as access: Restricted in metadata

📚 Exceptions and Special Cases

When to Deviate from Standards

Standards should be followed 99% of the time. Exceptions might include:

Valid reasons:

External requirement (client demands specific format)
Legacy document migration (keep original naming temporarily)
Technical limitation (system doesn’t support format)
Regulatory compliance (must follow external standard)

Process for exceptions:

Document reason for exception
Get approval from document hub owner
Add note in document explaining deviation
Plan to align with standards when possible

🔄 Continuous Improvement

These standards are living documents. If you identify:

❓ Unclear guideline
🐛 Inconsistency or error
💡 Improvement opportunity
🆕 New document type needing standard

Please:

Discuss with team
Propose change to document hub owner
Update standards if approved
Communicate changes to team

📞 Questions or Clarifications

Document Standards Owner: [Leadership/Operations Lead] Contact: [Email/Chat]

Quick Questions:

“Does this file name follow convention?” → Check examples above
“What status should I use?” → Check lifecycle section
“How do I version this?” → Check version control section

Can’t find answer? Ask document hub owner rather than guessing!

Version History

Version	Date	Changes	Author
1.0	2025-11-08	Initial document standards created	iSu Technologies Team

Document Standards maintained by iSu Technologies Operations Team Last Updated: November 8, 2025 These standards apply to all iSu Technologies documentation