From 317cd66b5ab41652658f4de35f3046b47b797356 Mon Sep 17 00:00:00 2001 From: smartupzeroadmin Date: Tue, 15 Jul 2025 08:07:41 +0000 Subject: [PATCH] Add 0_timline content stlye guide --- 0_timline-content-stlye-guide.md | 404 +++++++++++++++++++++++++++++++ 1 file changed, 404 insertions(+) create mode 100644 0_timline-content-stlye-guide.md diff --git a/0_timline-content-stlye-guide.md b/0_timline-content-stlye-guide.md new file mode 100644 index 0000000..0c8a65b --- /dev/null +++ b/0_timline-content-stlye-guide.md @@ -0,0 +1,404 @@ +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 | +|---------|-----------|--------| +| **Organizational Structure** | +| General Forum | `:material-forum:` | Public discussions, voting, governance | +| Workplace | `:material-briefcase:` | Worker-only spaces and content | +| Teams | `:material-account-group:` | Team-related content | +| Roles | `:material-card-account-details:` | Role definitions and assignments | +| Objectives | `:material-target:` | Project goals and missions | +| Tasks | `:material-checkbox-marked-circle:` | Individual work items | +| **Project Specifics** | +| ONLIFE | `:material-alert-decagram:` | Emergency network references | +| Smartup Model | `:material-atom:` | Core model concepts | +| Experiment | `:material-flask:` | Scientific method references | +| **Actions & States** | +| Vote | `:material-vote:` | Governance decisions | +| Join | `:material-account-plus:` | Recruitment/onboarding | +| Build | `:material-hammer:` | Development work | +| Success | `:material-check-circle:` | Completed/positive items | +| Warning | `:material-alert:` | Important notices | +| Info | `:material-information:` | Explanations | +| **Financial** | +| Treasury | `:material-currency-eur:` | Money/funding matters | +| Credits | `:material-coin:` | Smartup Credits (SC) | +| **Technical** | +| Code | `:material-code-tags:` | Development/repos | +| Infrastructure | `:material-server:` | Technical stack | +| Communication | `:material-chat:` | Matrix/Element | + +### 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: + +```markdown +# :material-icon: Page Title + +!!! info "What is this?" + One-sentence explanation of what this page covers. + +## Purpose (or The Why) + +Brief paragraph explaining why this matters in the Smartup Zero context. +``` + +### Status Indicators + +For showing project or phase status: + +```markdown +
+ +- :material-check-circle:{ .lg .middle } **Completed** + + --- + + What has been achieved + + [:octicons-arrow-right-24: View details](#) + +- :material-progress-clock:{ .lg .middle } **In Progress** + + --- + + What is currently being worked on + + [:octicons-arrow-right-24: Track progress](#) + +- :material-calendar-clock:{ .lg .middle } **Planned** + + --- + + What's coming next + + [:octicons-arrow-right-24: See roadmap](#) + +
+``` + +### Team Cards + +Standard format for presenting teams: + +```markdown +### :material-account-group: Team Name + +!!! tip inline end "Quick Links" + :material-git: [Team Repos](https://smartup-zero-forgejo.fly.dev/smartup-zero/team-name) + :material-chat: [Team Room](#3_team-name) + :material-clipboard-list: [Open Tasks](link) + +**Captain:** [@username](link) +**Members:** 5 active contributors +**Formed:** January 2025 + +**Mission:** One clear sentence describing the team's purpose. + +**Current Objectives:** +- Objective 1 with deadline +- Objective 2 with deadline +``` + +### Phase Documentation + +For describing project phases: + +```markdown +## :material-numeric-1-circle: Phase Name + +!!! success inline end "Phase Status" + **Status:** Active/Complete + **Duration:** 30 days + **Started:** Date + **Target:** Date + +### Goals for This Phase + +- [ ] Goal 1 with measurable outcome +- [x] Goal 2 (completed) +- [ ] Goal 3 with measurable outcome + +### Key Deliverables + +| Deliverable | Description | Status | +|-------------|-------------|---------| +| Item 1 | What it is | :material-check: Done | +| Item 2 | What it is | :material-progress-wrench: In Progress | +| Item 3 | What it is | :material-calendar: Planned | +``` + +### Call-to-Action Sections + +For encouraging participation: + +```markdown +## :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:](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 } + +
+``` + +## 📝 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: +```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)" + Detailed explanation here... +``` + +### 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 + +```markdown +!!! info "Smartup" + A new organizational model based on collective ownership, collective + craftsmanship, and collective governance. +``` + +### Warning Boxes + +```markdown +!!! warning "Experimental Phase" + This process is still being tested in our micro-pilot. + Procedures may change based on learnings. +``` + +### Example Boxes + +```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... +``` + +### Quote Boxes + +```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... +``` + +### Tabs for Multiple Perspectives + +```markdown +=== ":material-account: For Contributors" + + Information relevant to people wanting to contribute... + +=== ":material-currency-eur: For Supporters" + + Information for financial supporters... + +=== ":material-cellphone: For Future Users" + + Information about using ONLIFE... +``` + +### Expandable Details + +```markdown +??? question "Frequently Asked Question" + + The answer to the question... + +??? tip "Pro Tip" + + Advanced information for experienced users... +``` + +### Button Styles + +```markdown +[Primary Action :material-arrow-right:](#){ .md-button .md-button--primary } +[Secondary Action](#){ .md-button } +[Text Link with Icon :material-open-in-new:](#) +``` + +### Mermaid Diagrams + +```markdown +```mermaid +graph TD + A[Contributor] -->|Creates| B[Task] + B -->|Completes| C[Review] + C -->|Approves| D[SC Minted] + D -->|Logged in| E[Ledger] +``` +``` + +### Progress Indicators + +```markdown +!!! progress "Project Completion" + :material-progress-check: **65% Complete** + + - [x] Phase 0: Micro-Pilot + - [x] Infrastructure Setup + - [ ] ONLIFE MVP + - [ ] First Funding Round +``` + +## 🔧 Technical Formatting + +### Code Blocks + +Always specify language for syntax highlighting: + +```markdown +```python +def mint_credits(worker, amount): + """Mint Smartup Credits for completed work.""" + return ledger.add_entry(worker, amount) +``` +``` + +### File References + +```markdown +!!! file "ledger.log" + ```json + {"type": "mint", "worker": "@alice", "amount": 500, "task": "#42"} + ``` +``` + +### Terminal Commands + +```markdown +```console +$ git clone https://smartup-zero-forgejo.fly.dev/smartup-zero/0_timeline.git +$ cd 0_timeline +$ mkdocs serve +``` +``` + +## 📊 Tables and Data + +### Standard Table Format + +```markdown +| Column | Column | Column | +|--------|--------|--------| +| Data | Data | Data | +| Left-aligned | Center-aligned | Right-aligned | +``` + +### Status Tables + +```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 deploy | +``` + +## 🌐 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 + +```markdown +!!! seealso "Related Topics" + - [The Smartup Model](../0_timeline/the-smartup-hypothesis.md) + - [How to Contribute](../smartup-zero/2_workplace.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 \ No newline at end of file