Skip to content

Feoda Documentation Project — Project Instructions

Version: 1.0
Last Updated: 2026-02-18
Owner: Head of Technology
Status: Active

Table of Contents

  1. Purpose & Vision
  2. Folder Structure
  3. Naming Conventions
  4. Writing Style Guide
  5. Markdown Conventions
  6. Frontmatter Metadata Standard
  7. Template Usage Policy
  8. Client Documentation Rules
  9. Change Governance & Consistency Protocol
  10. Contribution Workflow
  11. Review & Ownership Model
  12. Versioning & History
  13. Future Considerations

1. Purpose & Vision

This repository is Feoda's single source of truth — the central, authoritative documentation for everything related to the company, its solutions, client implementations, technical architecture, processes, and policies.

Core Principle: Nothing Gets Lost

⚠️ No piece of information provided by a stakeholder — no matter how small — may be ignored or discarded. Every fact, detail, clarification, preference, or instruction shared by a team member must be captured somewhere in this documentation. If the information does not have an obvious home in the current structure, flag it and discuss where it belongs — but never silently drop it. This applies to all contributors, human and AI alike.

Goals

  • Onboarding: Any new joiner can read this documentation and understand what Feoda does, how its solutions work, and how the company operates.
  • Consistency: One place for all knowledge — no more scattered SharePoint documents, tribal knowledge, or undocumented processes.
  • Traceability: Every decision, process, and customization is documented with history tracked via Git.
  • AI-Readiness: The documentation is structured with consistent metadata and taxonomy so it can serve as a knowledge base for AI-assisted querying and retrieval in the future.
  • Accessibility: The documentation will eventually be published as an internal website accessible to all employees via a browser.
  • Completeness: Every piece of information provided is captured. Nothing is too small to document.

Scope

This documentation covers:

  • Company-level: About Feoda, glossary, onboarding guides, business processes, company policies
  • Solutions: ERP, ARM, EPM — features, processes, NetSuite bundle details
  • Client implementations: Per-client requirements, design, customizations, testing, deployment, support
  • Technical: Architecture, development guides, NetSuite specifics, frontend layer, infrastructure, runbooks, architecture decision records
  • Meetings: Extracted knowledge from team meetings and discussions

2. Folder Structure

Documentation/
├── PROJECT_INSTRUCTIONS.md          ← This file — master governance
├── README.md                        ← Repo landing page, navigation guide
├── CHANGELOG.md                     ← History of major documentation updates
│
├── doc-templates/                   ← Reusable templates for all document types
│
├── company/                         ← Company-wide, non-solution-specific docs
│   ├── about-feoda.md
│   ├── glossary.md
│   ├── onboarding/
│   ├── processes/
│   └── policies/
│
├── solutions/                       ← One folder per Feoda product line
│   ├── erp/
│   ├── arm/
│   └── epm/
│
├── clients/                         ← Per-client implementation documentation
│   ├── _template/                  ← Skeleton to copy for new clients
│   └── [client-name]/             ← One folder per client
│
├── tech/                            ← Technical documentation
│   ├── architecture/
│   ├── development/
│   ├── netsuite/
│   ├── frontend/
│   ├── infrastructure/
│   ├── runbooks/
│   └── decisions/
│
└── meetings/                        ← Meeting extractions & knowledge capture

Rules

  • Do not create folders outside this structure without updating this document first.
  • Every folder must contain a README.md that explains the purpose of that folder and what belongs in it.
  • Nesting depth: Maximum 4 levels deep from Documentation/. If you need more, reconsider the structure.
  • No orphan files: Every file must live in the appropriate folder as defined above.

3. Naming Conventions

Files

Rule Example
Use kebab-case (lowercase, hyphens) solution-design.md, go-live-checklist.md
Date-prefixed for chronological content 2026-02-18-arm-process-review.md
Use .md extension for all documentation —
No spaces, no underscores (except _template) —
Be descriptive but concise business-requirements.md not br.md

Folders

Rule Example
Use kebab-case fixed-assets/, payment-plans/
Client folders use the client's codename or short name green-valley-school/
Prefix template/skeleton folders with underscore _template/

Dates

  • Always use ISO 8601: YYYY-MM-DD (e.g., 2026-02-18)
  • In filenames: 2026-02-18-topic-name.md
  • In frontmatter: last-updated: 2026-02-18

4. Writing Style Guide

Audience Awareness

Every document has an intended audience. Tag it in the frontmatter and write accordingly:

Audience Tag Write For
all Anyone in the company — use plain, non-technical language
technical Developers, architects — technical detail is expected
functional Business analysts, project managers — process-focused
leadership Executives — high-level, outcome-focused
client-facing Support staff, client interactions — clear, professional

Style Rules

  1. Write in plain English. Avoid jargon unless it's in the glossary.
  2. Be concise. Say what needs to be said, nothing more.
  3. Use active voice. "The system generates invoices" not "Invoices are generated by the system."
  4. Use consistent terminology. Always refer to terms as defined in company/glossary.md. Do not invent synonyms.
  5. Define acronyms on first use. "Accounts Receivable Management (ARM)" — then use "ARM" thereafter.
  6. Use numbered steps for procedures. Use bullet points for lists of items.
  7. Include context. Don't assume the reader knows what you know. Link to related documents.
  8. Keep paragraphs short. 3-5 sentences maximum.
  9. Use examples. When explaining a concept or process, include a concrete example.
  10. Date your knowledge. If something is likely to change, note when it was last verified.

Language

  • Primary language: English
  • Arabic translations may be added later as a parallel structure, not inline.

5. Markdown Conventions

Heading Hierarchy

# Document Title (H1) — only ONE per document, matches the document's purpose
## Major Section (H2)
### Subsection (H3)
#### Detail (H4) — use sparingly
  • Never skip heading levels (e.g., don't go from H2 to H4).
  • H1 is reserved for the document title only.
  • Internal links: Use relative paths from the current file. 
    See [About Feoda](../company/about-feoda.md) for company overview.
  • External links: Use full URLs with descriptive text. 
    [Oracle NetSuite Documentation](https://docs.oracle.com/en/cloud/saas/netsuite/)

Code Blocks

  • Use fenced code blocks with language identifiers: 
    ```javascript
// SuiteScript example
```

Tables

  • Use Markdown tables for structured data.
  • Include a header row.
  • Align columns for readability in source.

Images

  • Store images in an assets/ subfolder within the relevant section.
  • Use descriptive alt text: ![ARM Dashboard showing payment plans](assets/arm-dashboard-payment-plans.png)

Callouts

Use blockquotes with emoji prefixes for callouts:

> ⚠️ **Warning**: This process requires admin access to NetSuite.

> ℹ️ **Note**: This feature is available in ARM v2.3+.

> ✅ **Best Practice**: Always test in sandbox before production.

6. Frontmatter Metadata Standard

Every document must begin with a YAML frontmatter block. This enables future site generation, search indexing, and AI retrieval.

---
title: "Document Title"
description: "One-line summary of what this document covers"
author: "Name or team"
created: YYYY-MM-DD
last-updated: YYYY-MM-DD
status: draft | in-review | approved | deprecated
audience: all | technical | functional | leadership | client-facing
tags:
  - tag1
  - tag2
owner: "Name or role responsible for keeping this document current"
related-documents:
  - path/to/related-doc-1.md
  - path/to/related-doc-2.md
---

Required Fields

Field Required Description
title ✅ Document title
description ✅ One-line summary
author ✅ Who wrote it
created ✅ Creation date
last-updated ✅ Last modification date
status ✅ Current status
audience ✅ Target reader
tags ✅ Searchable tags
owner ✅ Who maintains it
related-documents ✅ List of related documents (paths relative to repo root)

Status Lifecycle

draft → in-review → approved → (updated: back to in-review) → approved
                                                              → deprecated

Tags Taxonomy

Use consistent tags from this controlled vocabulary (expand as needed):

  • Solutions: erp, arm, epm
  • Functional areas: accounting, billing, payroll, budgeting, procurement, hr, reporting, fixed-assets, payment-plans
  • Technical: suitescript, netsuite, integration, api, frontend, infrastructure
  • Document types: process, architecture, runbook, decision-record, requirements, design, customization
  • Client-related: client-implementation, client-[name]

7. Template Usage Policy

Rule: Always Start from a Template

Every new document must be created from one of the templates in doc-templates/. Do not create documents from scratch.

Available Templates

Template Use For
solution-overview.md Documenting a Feoda solution (ERP, ARM, EPM)
process-document.md Business or operational process documentation
meeting-extraction.md Extracting knowledge from meeting recordings/transcripts
technical-spec.md Technical architecture, design documents
runbook.md Operational procedures, how-to guides
decision-record.md Architecture Decision Records (ADRs)
client-implementation.md Client project documentation (overview, requirements, design)

Process

  1. Copy the appropriate template.
  2. Fill in all frontmatter fields.
  3. Replace placeholder content with actual content.
  4. Remove any sections that don't apply (but add a note why if it's a major section).
  5. Fill in the related-documents field linking to all related documents.
  6. Submit for review per the contribution workflow.

Creating New Templates

If none of the existing templates fit, propose a new one:

  1. Create the template in doc-templates/ following the same conventions.
  2. Add it to the table above in this document.
  3. Submit for review and approval.

8. Client Documentation Rules

When to Create a Client Folder

Create a new folder under clients/ when:

  • A new client project begins (at the requirements stage or earlier).
  • An existing client engagement needs documentation that doesn't exist yet.

How to Create a Client Folder

  1. Copy clients/_template/ to clients/[client-name]/.
  2. Use kebab-case for the client folder name (e.g., green-valley-school/).
  3. Fill in overview.md with the client profile, contract scope, and timeline.
  4. Populate sections as the project progresses — not everything needs to be filled in immediately.

Mandatory vs. Optional Sections

Section When Required
overview.md Always — created when the folder is created
requirements/business-requirements.md Before design begins
requirements/technical-requirements.md Before development begins
design/solution-design.md Before development begins
design/integrations.md If the client has third-party integrations
design/data-migration.md If data migration is in scope
customizations/* If any customizations are made
testing/test-cases.md Before UAT begins
deployment/go-live-checklist.md Before go-live
support/known-issues.md After go-live

Confidentiality

  • Never include: Passwords, API keys, tokens, or other credentials.
  • Never include: Personally identifiable information (PII) of students, parents, or staff.
  • Use codenames if client confidentiality requires it — document the mapping separately in a secure location (not in this repo).
  • Financial terms: Do not include contract values, pricing, or payment terms unless explicitly approved.

Cross-Referencing Solutions

Client documentation should link to solution documentation, not duplicate it:

This client uses Feoda ARM for billing. See [ARM Overview](../../solutions/arm/overview.md)
for standard features. Client-specific customizations are documented below.

9. Change Governance & Consistency Protocol

⚠️ This section is mandatory for all contributors, including AI assistants.

9.1 Plan Before Execute

Every documentation change — whether new content, edits, restructuring, or deletions — must first be presented as a proposal before implementation.

A change proposal must include:

  1. What will change: Clear description of the intended modification.
  2. Which files/sections are affected: List of primary files AND all related files that reference the same information.
  3. Rationale: Why this change is needed.
  4. Impact assessment: What other documents, templates, or sections could be affected.

The proposal must be explicitly approved before any changes are made.

9.2 Cross-Reference Propagation

Any change to a piece of information must be reflected in every place that references it. There are no exceptions.

Examples:

If You Change... Also Update...
A solution's description in solutions/erp/overview.md company/about-feoda.md, any client docs referencing ERP, glossary.md if terminology changed
A process definition in company/processes/ All client docs that reference that process, any solution docs that describe the process
A term in company/glossary.md Every document that uses that term (search the entire repo)
A template in doc-templates/ Review all documents created from that template for alignment
Client-specific info in clients/[name]/ Related solutions/ docs if the customization reveals a gap in standard documentation

The related-documents frontmatter field exists specifically to make this traceable. Keep it accurate.

9.3 Pre-Implementation Consistency Audit

Before making any approved change, the implementer (human or AI) must:

  1. Search the entire project for all references to the affected content (terms, process names, feature descriptions, etc.).
  2. Flag any existing discrepancies found during the search — even if they are unrelated to the current change.
  3. Present a consistency report that includes:
  4. Files that will be updated as part of this change
  5. Discrepancies found elsewhere in the project
  6. Proposed fixes for each discrepancy
  7. Wait for approval of the full consistency report before executing any changes.

9.4 Post-Implementation Verification

After changes are applied, the implementer must:

  1. Re-scan affected files to confirm all updates landed correctly.
  2. Verify no orphaned references remain (links to moved/deleted content, outdated terminology, etc.).
  3. Update CHANGELOG.md with a summary of the change.
  4. Update last-updated frontmatter in every modified file.

9.5 Discrepancy Escalation

If a discrepancy is detected between documents at any point — even when not actively making changes:

  1. Flag it immediately. Do not ignore it.
  2. Do not proceed with the current task until the discrepancy is acknowledged by the document owner or project lead.
  3. Propose a resolution with a clear recommendation on which version of the information is correct.
  4. Document the resolution once decided — update all affected files and log the fix in CHANGELOG.md.

9.6 AI-Specific Rules

When an AI assistant is used to make documentation changes:

  • AI must never ignore any information provided by a stakeholder — no matter how minor it seems. If the information has no clear home in the current structure, AI must flag it and propose where to place it. Silently dropping information is a violation of the core principle (Section 1).
  • AI must always perform the pre-implementation consistency audit (Section 9.3) before making any change.
  • AI must present the change plan and consistency report to a human for approval.
  • AI must not auto-approve its own changes — a human must confirm.
  • AI should flag any ambiguity, conflicting information, or unclear ownership immediately.
  • AI must update all related documents in a single operation, not piecemeal.

10. Contribution Workflow

For All Contributors

1. Create a branch    → feature/[description] or docs/[description]
2. Make changes       → Following all rules in this document
3. Self-review        → Run the consistency checks in Section 9
4. Submit PR          → With a clear description of what changed and why
5. Peer review        → At least one reviewer who owns the affected section
6. Merge              → Squash merge to main
7. Update CHANGELOG   → Log the change with date and author

Branch Naming

Type Pattern Example
New content docs/add-[topic] docs/add-arm-billing-process
Updates docs/update-[topic] docs/update-erp-overview
Fixes docs/fix-[topic] docs/fix-glossary-typos
Restructuring docs/restructure-[area] docs/restructure-clients-folder
Client documentation docs/client-[name]-[topic] docs/client-greenvalley-requirements

Commit Messages

Use conventional commit format:

docs: add ARM billing process documentation
docs: update ERP overview with new fixed assets feature
docs: fix inconsistent terminology in glossary

11. Review & Ownership Model

Section Owners

Each top-level section has a designated owner responsible for accuracy and currency:

Section Owner Review Cadence
company/ Head of Technology Quarterly
solutions/ Product/Solution Lead Monthly
clients/ Project Manager per client Per milestone
tech/ Head of Technology / Lead Developer Monthly
meetings/ Meeting facilitator Per meeting
doc-templates/ Head of Technology As needed

Review Responsibilities

Owners must:

  • Review PRs that touch their section.
  • Conduct periodic reviews per the cadence above.
  • Ensure content is current and accurate.
  • Update last-updated dates after review (even if no changes were made — to confirm it's still accurate).

12. Versioning & History

Git as Version Control

  • All documentation lives in this Git repository.
  • History is tracked through Git commits.
  • Use branches and PRs for all changes (no direct commits to main).

CHANGELOG.md

Maintain a human-readable changelog at the root of the repository. Every significant change must be logged:

## [YYYY-MM-DD] - Brief Description
- **Added**: New documents or sections
- **Changed**: Updates to existing content
- **Fixed**: Corrections to errors or inconsistencies
- **Removed**: Deprecated or deleted content

Document Status

Use the status frontmatter field to track each document's lifecycle:

  • draft: Work in progress, not yet reviewed.
  • in-review: Submitted for review, pending approval.
  • approved: Reviewed and accepted as accurate.
  • deprecated: No longer current — kept for historical reference, with a note pointing to the replacement.

13. Future Considerations

These are planned but not yet implemented. Keep them in mind when creating content:

Internal Documentation Website

  • The documentation will be published as an internal website using a static site generator (Docusaurus is the current recommendation — React-based, good search, sidebar navigation, versioning).
  • Frontmatter fields (title, description, tags, sidebar position) will map directly to site navigation.
  • Write Markdown that renders well both on GitHub and in a static site.

AI-Assisted Querying

  • This documentation is intended to serve as a knowledge base for AI retrieval (RAG — Retrieval-Augmented Generation).
  • Consistent metadata, clear headings, self-contained documents, and explicit cross-references make AI retrieval more accurate.
  • The tags taxonomy, related-documents field, and description field are specifically designed for this purpose.
  • Keep documents self-contained where possible — a document should make sense on its own without requiring the reader to navigate five other files for context.

Multi-Language Support

  • Arabic translations may be added in the future as a parallel folder structure (e.g., company/ar/about-feoda.md).
  • Do not mix languages within a single document.

Migration from SharePoint

  • Existing documentation on SharePoint will be gradually migrated to this repository.
  • When migrating, always adapt content to follow the conventions in this document — do not copy-paste without reformatting.

This document is the ultimate authority on how documentation is created, maintained, and governed at Feoda. When in doubt, refer here. If something is missing, propose an addition through the standard contribution workflow.