1_general_forum/docs/style-guide.md

# 📖 0_timeline Content Style Guide

!!! info "Purpose"
    This guide ensures consistent content across the 0_timeline website. All contributors should reference this when creating or editing content. Our goal is to make complex ideas accessible while maintaining the experimental, transparent spirit of Smartup Zero.

## 🎨 Visual Language

### Icon Dictionary

Always use these icons for consistency across all pages:

| Concept | Icon Code | Usage | Preview |
|---------|-----------|--------|---------|
| **Organizational Structure** |
| General Forum | `:material-forum:` | Public discussions, voting, governance | :material-forum: |
| Workplace | `:material-briefcase:` | Worker-only spaces and content | :material-briefcase: |
| Teams | `:material-account-group:` | Team-related content | :material-account-group: |
| Roles | `:material-card-account-details:` | Role definitions and assignments | :material-card-account-details: |
| Objectives | `:material-target:` | Project goals and missions | :material-target: |
| Tasks | `:material-checkbox-marked-circle:` | Individual work items | :material-checkbox-marked-circle: |
| **Project Specifics** |
| ONLIFE | `:material-alert-decagram:` | Emergency network references | :material-alert-decagram: |
| Smartup Model | `:material-atom:` | Core model concepts | :material-atom: |
| Experiment | `:material-flask:` | Scientific method references | :material-flask: |
| **Actions & States** |
| Vote | `:material-vote:` | Governance decisions | :material-vote: |
| Join | `:material-account-plus:` | Recruitment/onboarding | :material-account-plus: |
| Build | `:material-hammer:` | Development work | :material-hammer: |
| Success | `:material-check-circle:` | Completed/positive items | :material-check-circle: |
| Warning | `:material-alert:` | Important notices | :material-alert: |
| Info | `:material-information:` | Explanations | :material-information: |
| **Financial** |
| Treasury | `:material-currency-eur:` | Money/funding matters | :material-currency-eur: |
| Credits | `:material-coin:` | Smartup Credits (SC) | :material-hand-coin: |
| **Technical** |
| Code | `:material-code-tags:` | Development/repos | :material-code-tags: |
| Infrastructure | `:material-server:` | Technical stack | :material-server: |
| Communication | `:material-chat:` | Matrix/Element | :material-chat: |

### Color Philosophy

- **Primary (Amber)** 🟨: Energy, innovation, warmth - use for main CTAs and highlights
- **Accent (Lime)** 🟩: Growth, freshness, progress - use for success states and secondary actions
- **Semantic Colors**: Use mkdocs-material's built-in admonition colors for meaning

## 📐 Content Patterns

### Page Headers

Every page should start with a clear hierarchy.

**Example Code:**
~~~markdown
###:material-forum: Our General Forum

!!! info "What is this?"
    The public square for all Smartup Zero owners where governance happens.

### Purpose

This is where we make collective decisions that shape our project's future.
~~~

**Renders as:**

###:material-forum: Our General Forum

!!! info "What is this?"
    The public square for all Smartup Zero owners where governance happens.

**Purpos**e

This is where we make collective decisions that shape our project's future.


### Status Indicators

For showing project or phase status.

**Example Code:**
~~~markdown
<div class="grid cards" markdown>

- :material-check-circle:{ .lg .middle } **Infrastructure**

    ---

    Core services deployed and operational
    
    [:octicons-arrow-right-24: View details](#)

- :material-progress-clock:{ .lg .middle } **ONLIFE Development**

    ---

    Building the MVP emergency network
    
    [:octicons-arrow-right-24: Track progress](#)

- :material-calendar-clock:{ .lg .middle } **First Funding**

    ---

    Crowdfunding campaign preparation
    
    [:octicons-arrow-right-24: See timeline](#)

</div>
~~~

**Renders as:**

<div class="grid cards" markdown>

- :material-check-circle:{ .lg .middle } **Infrastructure**

    ---

    Core services deployed and operational
    
    [:octicons-arrow-right-24: View details](#)

- :material-progress-clock:{ .lg .middle } **ONLIFE Development**

    ---

    Building the MVP emergency network
    
    [:octicons-arrow-right-24: Track progress](#)

- :material-calendar-clock:{ .lg .middle } **First Funding**

    ---

    Crowdfunding campaign preparation
    
    [:octicons-arrow-right-24: See timeline](#)

</div>

---

### Team Cards

Standard format for presenting teams.

**Example Code:**
~~~markdown
**:material-account-group: Development Team**

<aside class="md-typeset" markdown>
!!! tip inline end "Quick Links"
    :material-git: [Team Repos](https://smartup-zero-forgejo.fly.dev/smartup-zero/dev-team)  
    :material-chat: [Team Room](#3_dev-team)  
    :material-clipboard-list: [Open Tasks](#)
</aside>

**Captain:** [@alice](https://matrix.to/#/@alice:matrix.org)  
**Members:** 5 active contributors  
**Formed:** January 2025  

**Mission:** Build the ONLIFE emergency communication protocol and apps.

**Current Objectives:**
- Complete Android MVP by Feb 28
- Implement mesh networking core
~~~

**Renders as:**

**:material-account-group: Development Team**

<aside class="md-typeset" markdown>
!!! tip inline end "Quick Links"
    :material-git: [Team Repos](https://smartup-zero-forgejo.fly.dev/smartup-zero/dev-team)    
    :material-chat: [Team Room](#3_dev-team)    
    :material-clipboard-list: [Open Tasks](#)  
</aside>

**Captain:** [@alice](https://matrix.to/#/@alice:matrix.org)  
**Members:** 5 active contributors  
**Formed:** January 2025  

**Mission:** Build the ONLIFE emergency communication protocol and apps.

**Current Objectives:**
- Complete Android MVP by Feb 28
- Implement mesh networking core

---

### Phase Documentation

For describing project phases.

**Example Code:**
~~~markdown
**:material-numeric-0-circle: Phase 0: Micro-Pilot**

<aside class="md-typeset" markdown>
!!! info inline end "Phase Status"
    **Status:** Active  
    **Duration:** 30 days  
    **Started:** Jan 1, 2025  
    **Target:** Jan 31, 2025
</aside>

**Goals for This Phase**

- [x] Deploy core infrastructure
- [ ] Onboard 15-20 contributors
- [ ] Complete one full work cycle

**Key Deliverables**

| Deliverable | Description | Status |
|-------------|-------------|---------|
| Tech Stack | Forgejo + Matrix deployed | :material-check: Done |
| Engelbot | Automation bot v0.1 | :material-progress-wrench: In Progress |
| First Task | Test the SC system | :material-calendar: Planned |
~~~

**Renders as:**

**:material-numeric-0-circle: Phase 0: Micro-Pilot**

!!! info inline end "Phase Status"
    **Status:** Active  
    **Duration:** 30 days  
    **Started:** Jan 1, 2025  
    **Target:** Jan 31, 2025

**Goals for This Phase**

- [x] Deploy core infrastructure
- [ ] Onboard 15-20 contributors  
- [ ] Complete one full work cycle

**Key Deliverables**

| Deliverable | Description | Status |
|-------------|-------------|---------|
| Tech Stack | Forgejo + Matrix deployed | :material-check: Done |
| Engelbot | Automation bot v0.1 | :material-progress-wrench: In Progress |
| First Task | Test the SC system | :material-calendar: Planned |

---

### Call-to-Action Sections

For encouraging participation.

**Example Code:**
~~~markdown
**:material-rocket-launch: Ready to Contribute?**

<div class="grid" markdown>

:material-account-plus:{ .lg }

**Join the Project**

Become a Smartup Zero owner

[Join via Open Collective :material-open-in-new:](https://opencollective.com/smartup-zero){ .md-button }

:material-chat:{ .lg }

**Start Discussing**

Connect with the community

[Enter Matrix Space :material-open-in-new:](#){ .md-button }

:material-hammer:{ .lg }

**Start Building**

Pick up your first task

[Browse Open Tasks :material-open-in-new:](#){ .md-button }

</div>
~~~

**Renders as:**

**:material-rocket-launch: Ready to Contribute?**

<div class="grid" markdown>

:material-account-plus:{ .lg }

**Join the Project**

Become a Smartup Zero owner

[Join via Open Collective :material-open-in-new:](https://opencollective.com/smartup-zero){ .md-button }

:material-chat:{ .lg }

**Start Discussing**

Connect with the community

[Enter Matrix Space :material-open-in-new:](#){ .md-button }

:material-hammer:{ .lg }

**Start Building**

Pick up your first task

[Browse Open Tasks :material-open-in-new:](#){ .md-button }

</div>

## 📝 Writing Guidelines

### Voice & Tone

- **Inclusive**: Always "we" not "I" or "they"
- **Experimental**: Acknowledge we're learning ("we believe", "our hypothesis")
- **Transparent**: Share both successes and challenges
- **Accessible**: Explain technical terms on first use

### Structure Guidelines

1. **Start with Why**: Lead with purpose/problem before solution
2. **Show, Don't Just Tell**: Use examples and diagrams
3. **Progressive Disclosure**: Overview first, details in expandable sections

**Example Code:**
~~~markdown
** The Smartup Credit System

**Why it exists:** We need a fair way to track and reward contributions before cash arrives.

??? info "How it works (Technical Details)"
    When a contributor completes a task, the Team Captain approves it and 
    Smartup Credits are minted to the ledger. These credits represent a 
    future claim on treasury funds at a 1 SC = 1 EUR rate.
~~~

**Renders as:**

**The Smartup Credit System**

**Why it exists:** We need a fair way to track and reward contributions before cash arrives.

??? info "How it works (Technical Details)"
    When a contributor completes a task, the Team Captain approves it and 
    Smartup Credits are minted to the ledger. These credits represent a 
    future claim on treasury funds at a 1 SC = 1 EUR rate.

### Common Phrases

Use these standardized phrases:

- "Smartup Zero" (not "SmartUp" or "smartup")
- "Smartup Credits (SC)" on first mention, then "SC"
- "the experiment" (lowercase when referring to our project)
- "collective ownership/craftsmanship/governance" (our three pillars)
- "ONLIFE" (all caps - it's an acronym)

## 🧩 Component Library

### Definition Boxes

**Example Code:**
~~~markdown
!!! info "Smartup"
    A new organizational model based on collective ownership, collective 
    craftsmanship, and collective governance.
~~~

**Renders as:**

!!! info "Smartup"
    A new organizational model based on collective ownership, collective 
    craftsmanship, and collective governance.

---

### Warning Boxes

**Example Code:**
~~~markdown
!!! warning "Experimental Phase"
    This process is still being tested in our micro-pilot. 
    Procedures may change based on learnings.
~~~

**Renders as:**

!!! warning "Experimental Phase"
    This process is still being tested in our micro-pilot. 
    Procedures may change based on learnings.

---

### Example Boxes

**Example Code:**
~~~markdown
!!! example "How This Works in Practice"
    When a developer completes a task worth 500 SC, the Team Captain 
    approves it, triggering an automatic ledger update via Engelbot.
~~~

**Renders as:**

!!! example "How This Works in Practice"
    When a developer completes a task worth 500 SC, the Team Captain 
    approves it, triggering an automatic ledger update via Engelbot.

---

### Quote Boxes

**Example Code:**
~~~markdown
!!! quote "Our Inscription"
    We don't accept our reality but seek to alter it. We are not too late 
    or too early but precisely on time. The next big thing will be a mosaic 
    of small things.
~~~

**Renders as:**

!!! quote "Our Inscription"
    We don't accept our reality but seek to alter it. We are not too late 
    or too early but precisely on time. The next big thing will be a mosaic 
    of small things.

---

### Tabs for Multiple Perspectives

**Example Code:**
~~~markdown
=== ":material-account: For Contributors"

    Learn how to join the project and start earning Smartup Credits 
    by contributing your skills to building ONLIFE.

=== ":material-currency-eur: For Supporters"

    Discover how your financial support directly enables the development 
    of public-good technology with transparent fund allocation.

=== ":material-cellphone: For Future Users"

    Understand how ONLIFE will provide emergency communication when 
    traditional networks fail.
~~~

**Renders as:**

=== ":material-account: For Contributors"

    Learn how to join the project and start earning Smartup Credits 
    by contributing your skills to building ONLIFE.

=== ":material-currency-eur: For Supporters"

    Discover how your financial support directly enables the development 
    of public-good technology with transparent fund allocation.

=== ":material-cellphone: For Future Users"

    Understand how ONLIFE will provide emergency communication when 
    traditional networks fail.

---

### Expandable Details

**Example Code:**
~~~markdown
??? question "What are Smartup Credits?"

    Smartup Credits (SC) are internal units that track contributions 
    before cash is available. 1 SC = 1 EUR claim on the treasury.

??? tip "Pro Tip: Claiming Your First Task"

    Start with tasks labeled "good-first-task" in Forgejo. Comment 
    on the issue to claim it before starting work.
~~~

**Renders as:**

??? question "What are Smartup Credits?"

    Smartup Credits (SC) are internal units that track contributions 
    before cash is available. 1 SC = 1 EUR claim on the treasury.

??? tip "Pro Tip: Claiming Your First Task"

    Start with tasks labeled "good-first-task" in Forgejo. Comment 
    on the issue to claim it before starting work.

---

### Button Styles

**Example Code:**
~~~markdown
[Primary Action :material-arrow-right:](#){ .md-button .md-button--primary }
[Secondary Action](#){ .md-button }
[Text Link with Icon :material-open-in-new:](#)
~~~

**Renders as:**

[Primary Action :material-arrow-right:](#){ .md-button .md-button--primary }
[Secondary Action](#){ .md-button }
[Text Link with Icon :material-open-in-new:](#)

---

### Mermaid Diagrams

**Example Code:**
~~~markdown
```mermaid
graph TD
    A[Contributor] -->|Creates| B[Task]
    B -->|Completes| C[Review]
    C -->|Approves| D[SC Minted]
    D -->|Logged in| E[Ledger]
```
~~~

**Renders as:**

```mermaid
graph TD
    A[Contributor] -->|Creates| B[Task]
    B -->|Completes| C[Review]
    C -->|Approves| D[SC Minted]
    D -->|Logged in| E[Ledger]
```

---

### Progress Indicators

**Example Code:**
~~~markdown
!!! abstract "Micro-Pilot Progress"
    :material-progress-check: **35% Complete**
    
    - [x] Infrastructure deployed
    - [x] Core team assembled
    - [ ] First work cycle
    - [ ] Binding vote held
~~~

**Renders as:**

!!! abstract "Micro-Pilot Progress"
    :material-progress-check: **35% Complete**
    
    - [x] Infrastructure deployed
    - [x] Core team assembled
    - [ ] First work cycle
    - [ ] Binding vote held

## 🔧 Technical Formatting

### Code Blocks

Always specify language for syntax highlighting.

**Example Code:**
~~~markdown
```python
def mint_credits(worker, amount):
    """Mint Smartup Credits for completed work."""
    return ledger.add_entry(worker, amount)
```
~~~

**Renders as:**

```python
def mint_credits(worker, amount):
    """Mint Smartup Credits for completed work."""
    return ledger.add_entry(worker, amount)
```

---

### File Contents

**Example Code:**
~~~markdown
!!! example "ledger.log"
    ```json
    {"type": "mint", "worker": "@alice", "amount": 500, "task": "#42"}
    ```
~~~

**Renders as:**

!!! example "ledger.log"
    ```json
    {"type": "mint", "worker": "@alice", "amount": 500, "task": "#42"}
    ```

---

### Terminal Commands

**Example Code:**
~~~markdown
```console
$ git clone https://smartup-zero-forgejo.fly.dev/smartup-zero/0_timeline.git
$ cd 0_timeline
$ mkdocs serve
INFO - Building documentation...
INFO - Documentation built in 2.43 seconds
```
~~~

**Renders as:**

```console
$ git clone https://smartup-zero-forgejo.fly.dev/smartup-zero/0_timeline.git
$ cd 0_timeline
$ mkdocs serve
INFO - Building documentation...
INFO - Documentation built in 2.43 seconds
```

## 📊 Tables and Data

### Standard Table Format

**Example Code:**
~~~markdown
| Component | Status | Notes |
|-----------|--------|-------|
| Matrix Server | :material-check-circle: Operational | 99.9% uptime |
| Forgejo | :material-check-circle: Operational | v1.21.3 |
| Engelbot | :material-progress-wrench: In Progress | v0.1 pending |
~~~

**Renders as:**

| Component | Status | Notes |
|-----------|--------|-------|
| Matrix Server | :material-check-circle: Operational | 99.9% uptime |
| Forgejo | :material-check-circle: Operational | v1.21.3 |
| Engelbot | :material-progress-wrench: In Progress | v0.1 pending |

## 🌐 Linking Strategy

### Internal Links

- Use relative paths: `[Team Structure](../smartup-zero/3_teams.md)`
- Link to sections: `[Voting Process](1_general_forum.md#voting)`

### External Links

- Always add icon: `[Open Collective :material-open-in-new:](https://opencollective.com/smartup-zero)`
- Use descriptive text, not "click here"

### Cross-References

**Example Code:**
~~~markdown
!!! tip "Related Topics"
    - [The Smartup Model](../0_timeline/the-smartup-hypothesis.md)
    - [How to Contribute](../smartup-zero/2_workplace.md)
    - [Team Structure](../smartup-zero/3_teams.md)
~~~

**Renders as:**

!!! tip "Related Topics"
    - [The Smartup Model](../0_timeline/the-smartup-hypothesis.md)
    - [How to Contribute](../smartup-zero/2_workplace.md)
    - [Team Structure](../smartup-zero/3_teams.md)

### ✅ Checklist for New Pages

Before publishing any new page, ensure:

- [ ] Uses appropriate icon in title
- [ ] Has "What is this?" info box
- [ ] Follows voice & tone guidelines
- [ ] Includes at least one visual element (diagram, table, or card grid)
- [ ] Has clear CTAs if applicable
- [ ] Links to related content
- [ ] Uses consistent terminology
- [ ] Mobile-friendly (test grid layouts)

## 🚀 Quick Start Template

Copy this template when creating new pages:

~~~markdown
**:material-icon: Page Title

!!! info "What is this?"
    One-sentence explanation of what this page covers.

**Purpose**

Brief paragraph explaining why this matters in the Smartup Zero context.

**Main Content**

Your content here, following the patterns above...

**:material-rocket-launch: Next Steps**

What the reader should do after reading this page.

!!! tip "Related Topics"
    - [Related Page 1](link)
    - [Related Page 2](link)
~~~

---

!!! success "Ready to Create Content!"
    Now you have all the patterns and examples needed to create consistent, 
    beautiful content for 0_timeline. Remember to reference 
    this guide whenever you're unsure about formatting or style choices.