smartup-zero
/
1_general_forum
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
1_general_forum/docs/style-guide.md

18 KiB
Raw Blame History

📖 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:

###: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.

Purpose

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

Status Indicators

For showing project or phase status.

Example Code:

<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:

Team Cards

Standard format for presenting teams.

Example Code:

**: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

Captain: @alice
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:

**: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

  • 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:

**: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?

:material-account-plus:{ .lg }

Join the Project

Become a Smartup Zero owner

Join via Open Collective :material-open-in-new:{ .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 }

📝 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:

** 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:

!!! 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:

!!! 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:

!!! 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:

!!! 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:

=== ":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:

??? 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:

[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:

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

Renders as:

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:

!!! 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:

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

Renders as:

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

File Contents

Example Code:

!!! 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:

```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:

$ 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:

| 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:

!!! 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 - How to Contribute - Team Structure

✅ 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:

**: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.