Add 0_timline content stlye guide
parent
1c1237932b
commit
317cd66b5a
|
|
@ -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
|
||||
<div class="grid cards" 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](#)
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
### 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?
|
||||
|
||||
<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:
|
||||
```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
|
||||
Loading…
Reference in New Issue