contribution-guidelines

Pocket Space Contribution Guidelines

Rules for keeping the shared drive consistent, organized, and AI-readable.

Authorship

• Include your name at the top of any file you create (e.g., Author: David, Feb 2026).
• When making significant edits to an existing file, add your name if it isn't already there.
• Do NOT include the author's name in the file name.

File Format Rules

1. Markdown (.md) and Excel (.xlsx) for all planning files — brainstorming, research, meeting notes, roadmaps, open questions, ideation, and any working/in-progress documents. Use .md for files that do not require input from multiple users.
2. Word (.docx) only for final deliverables — polished reports, formal letters, or documents that require ongoing collaboration or input from multiple users. Do not use .docx for planning or research. Do not make .docx files unless explicitly asked.
3. Excel (.xlsx) for tabular data and spreadsheets.
4. Allowed formats: .md, .docx, .xlsx, .csv, .json — nothing else.
5. Do not use Google Docs — all documents must be stored as local files (.md, .docx, etc.) in this shared drive, not as Google Docs links or files.

Naming Conventions

• Use underscores instead of spaces: My_Document.md not My Document.md
• Use descriptive names: SocialFi_Market_Analysis.xlsx not Analysis.xlsx
• For versioned docs, use _Current suffix for the canonical version: FRD_Current.md
• Date-prefixed for chronological files: 2025-01-29_Meeting_Notes.md

Before Making Changes

1. Always read the README.md in a folder before making any changes to it.
2. README files contain important context about what exists and its purpose.
3. Check if a file already exists before creating a new one.

After Making Changes

1. Update the relevant README.md to reflect any new, modified, or deleted files.
2. If creating a new folder, add a README.md to it.

README Writing Guidelines

• Be parsimonious. Keep content high-level and concise — say only what is needed to orient the reader.
• Focus on what the folder is about, not what individual files it contains. Do not list or reference specific files.
• Describe subfolders. After explaining the folder's purpose, list any subfolders and briefly state what each one is for.

Research Folder Rule for .docx Deliverables

Every .docx deliverable must live inside a dedicated topic folder alongside a Research/ subfolder containing all the .md source files used to generate it.

Required structure:

[Department_Folder]/
└── [Topic_of_Research]/
    ├── [Topic_of_Research].docx       ← The deliverable
    └── Research/                       ← All source .md files
        ├── README.md                   ← Describes contents of this research folder
        ├── Landscape_Research.md
        ├── Comparison_Matrix.md
        ├── Segment_A/                  ← Can be deeply nested
        │   ├── Segment_A_Deep_Dive.md
        │   └── Sub_Topic/
        │       └── Sub_Topic_Research.md
        ├── Segment_B/
        │   └── Segment_B_Deep_Dive.md
        └── ...

Rules:

• The topic folder and .docx share the same name (e.g., SocialFi_Market_Analysis/SocialFi_Market_Analysis.docx)
• The Research/ subfolder must contain a README.md describing its contents
• All .md files referenced in the .docx must live inside Research/ or its subfolders
• The Research/ folder can be deeply nested — use subfolders to organize by segment, topic, or phase
• The .docx must hyperlink to files inside its Research/ folder
• If research files already exist elsewhere in the drive, copy or move them into Research/ so the deliverable and its sources are self-contained

Folder Placement Rules

• _Active/ — Only current, relevant documents
• _Archive/ — Historical documents, organized by era/pivot
• _Meeting_Notes/ — Organized by YYYY-MM subfolders
• Never place files at the root level unless they are project-wide (like README.md)