diff --git a/README.md b/README.md index 96c676b..01c3057 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,19 @@ Why do we need directory standards? Most directories are named after the file-type (i.e. suffix or software) they contain. +- [Designish](mod/designish/README.md) (**lifecycle-driven**): + Built around the **product lifecycle** and the **design process**. + Directories are named after the *phase* a file belongs to, + not the file type it contains — making a project's maturity and + progress immediately visible to contributors of all backgrounds, + including designers with no prior Git experience. + Top-level numbered areas (`10_management/`, `20_legal/`, + `30_engineering/`, `40_stewardship/`, `50_usage/`) provide a + clear visual progress map, while a 5-phase creative pipeline + inside `30_engineering/` guides teams from concept to release. + A dedicated `40_stewardship/` section covers maintenance, repair, + and recovery — supporting circular economy principles. + ## Other structure templates - diff --git a/designish-structure.md b/designish-structure.md new file mode 100644 index 0000000..75d3f59 --- /dev/null +++ b/designish-structure.md @@ -0,0 +1,107 @@ +# Designish — OSH Project Directory Structure (Circular & Lifecycle-Driven) + +**Principle:** "Process over product" — lifecycle-driven, designer-friendly, and circular. + +The **Designish** standard is built around the **product lifecycle** and the **design process**. Instead of naming directories after file types or technical domains, they are named after the **phase** a file belongs to. This approach makes a project's maturity, progress, and sustainability path immediately visible to contributors of all backgrounds. + +--- + +## Naming Rules + +- **Numbered prefixes:** `10_`, `20_`, `30_` for top-level areas; `01_`, `02_`, ... for sub-phases. + +- **Lowercase with underscores:** `assembly_guide` not `AssemblyGuide` or `assembly-guide`. + +- **Descriptive phase names:** `03_make` not `output` or `export`. + + +--- + +## Directory Tree + + +``` m + +root((my-osh-project)) +├── LICENSES/ # REUSE license files (CERN-OHL, GPL, CC-BY-SA) +├── README.md # Project overview +├── okh.toml # Open Know-How manifest for crawlers & indexers +├── 10_management/ # The Studio — "Why" and "Who" +│ ├── 01_roadmap/ # Visual timelines and milestones +│ ├── 02_meetings/ # Community sync notes (YYYY-MM-DD_topic.md) +│ ├── 03_stakeholders/ # Map of contributors and community members +│ ├── input/ # Incoming briefs and stakeholder requests +│ └── output/ # Approved plans and mandates +├── 20_legal/ # The Safety Net — Open Source protection +│ ├── compliance/ # CE/FCC certificates and test reports +│ ├── input/ # Draft agreements and incoming requests +│ └── output/ # Signed licenses and legal approvals +├── 30_engineering/ # The Creative Pipeline — 5-Phase Process +│ ├── 01_concept/ # The Sketchbook — Ideas & Requirements +│ │ ├── requirements/ # Functional & sustainability requirements +│ │ ├── moodboards/ # Visual explorations and block diagrams +│ │ └── adr/ # Architecture Decision Records (NNN_topic.md) +│ ├── 02_design/ # The Workbench — Discipline-organized sources +│ │ ├── electronics/ # Schematics and PCB layouts (KiCad) +│ │ ├── mechanical/ # 3D CAD (FreeCAD/STEP) and 2D drawings +│ │ ├── wear_parts/ # Components designed for frequent replacement [NEW] +│ │ └── firmware/ # The "brain" of the hardware +│ ├── 03_make/ # The Factory — Everything to build one unit +│ │ ├── bom/ # Bill of Materials (CSV/MD with material data) +│ │ ├── assembly_guide/ # Visual step-by-step instructions +│ │ └── fabrication_files/ # Ready-to-manufacture files (STL, DXF, Gerbers) +│ ├── 04_validation/ # The Lab — Safety & Prototype testing +│ │ ├── safety/ # Risk analysis (FMEA) +│ │ └── test_reports/ # Documentation of what worked or broke +│ └── 05_release/ # The Gallery — Sharing with the world +│ ├── oshwa_certification/ # OSHWA compliance evidence +│ └── media/ # Hero shots, videos, and press kits +├── 40_stewardship/ # Circularity — Repair & Recovery [NEW] +│ ├── 01_maintenance/ # Cleaning, calibration, and upkeep logs [NEW] +│ ├── 02_repair/ # Troubleshooting and disassembly guides [NEW] +│ └── 03_recovery/ # Recycling paths and upcycling ideas [NEW] +└── 50_usage/ # Implementation & Examples + └── example/ # Settings, samples, and use-cases +``` + +--- + +## Key Characteristics + +|**Property**|**Value**| +|---|---| +|**Naming Style**|Lifecycle phase (e.g., `10_management/`, `30_engineering/01_concept/`)| +|**Modularity**|Flat — single product; sub-assemblies live inside `02_design/`| +|**Decision Tracking**|ADRs in `01_concept/adr/` — design rationale is first-class| +|**Circular Focus**|Maintenance, Repair, and Recovery are prioritized in `40_stewardship/` [NEW]| +|**Handoff Zones**|`input/` and `output/` folders act as zones between disciplines| +|**Generated Files**|Explicitly separated in `fabrication_files/`| + +--- + +## Why this works for Designers & Circularity + +1. **Logical Flow**: Teams move naturally from `01_concept` to `05_release`. + +2. **No "Code" Required**: Contributors work in discipline-specific folders using familiar tools. + +3. **Sustainability by Design**: By pairing assembly with **disassembly** and **recovery** guides, the project moves from a linear to a circular lifecycle. + +4. **Transparency**: Keeping `ADRs` and `test_reports` visible allows the "Trial and Error" process to become a community learning resource. + + +--- + +## Recommended For + +Designer-led teams, sustainable hardware startups, and OSH projects aiming for long-term community stewardship and environmental responsibility. + +## References + +- `definition.csv` — machine-readable source + +- `okh.toml` — Open Know-How (OKH) specification + +- `REUSE specification` — License management + +- `9R Framework` — Circular Economy principles [NEW] \ No newline at end of file diff --git a/mod/designish/README.md b/mod/designish/README.md new file mode 100644 index 0000000..d12f6d9 --- /dev/null +++ b/mod/designish/README.md @@ -0,0 +1,145 @@ + + +# Designish - OSH project directory structure standards + +In short: **Lifecycle-driven and designer-friendly** + +The basic idea here is that directories are named after the *phase of the +design lifecycle* they belong to, rather than the file types they contain. +This makes the project's maturity and progress immediately visible to +contributors of all backgrounds — including designers with no prior Git +experience. + +The structure follows a 5-phase creative pipeline inside `30_engineering/`, +preceded by management (`10_management/`) and legal (`20_legal/`) top-level +concerns. + +## Definition + +This standards machine-readable definition, +can be found in various formats here: + +- [definition.csv](definition.csv) + ([format](../../definition_format.md)) + \- source, machine-readable, contains all the data + \- **use this for editing** +- [file-listing]( + https://osegermany.gitlab.io/osh-dir-std/mod/designish/listing.txt) + \- like the output of `find` in a sample repo + \- generated +- [tree]( + https://osegermany.gitlab.io/osh-dir-std/mod/designish/tree.html) + \- like the output of `tree` in a sample repo + \- generated, **recommended** for inspection + +## Guiding principles & Inspirations + +This standard is inspired by design studio workflows and product development +pipelines, where a contributor's first question is *"where are we in the +process?"* rather than *"what file type is this?"* + +Key principles: + +- **Phase visibility**: Numbered top-level phases (`10_`, `20_`, `30_`) and + numbered sub-phases (`01_concept`, `02_design`, …) act as a visual + progress map. +- **Designer-first**: No code background required — a designer naturally + moves from `01_concept` to `05_release`. +- **Decision transparency**: Architecture Decision Records (`adr/`) are + first-class citizens, keeping design rationale visible to the community. +- **Fabrication as a phase**: `03_make/fabrication_files/` separates + manufacture-ready exports from editable sources in `02_design/`. + +Some inspirations: + +- +- + +## Structure Overview + +```mermaid +graph TD + ROOT["my-osh-project/"] + ROOT --> LIC["LICENSES/"] + ROOT --> LICENSE["LICENSE"] + ROOT --> README["README.md"] + ROOT --> OKH["okh.toml"] + ROOT --> MGT["10_management/"] + ROOT --> LEG["20_legal/"] + ROOT --> ENG["30_engineering/"] + + MGT --> MGT1["01_roadmap/"] + MGT --> MGT2["02_meetings/"] + MGT --> MGT3["03_stakeholders/"] + MGT --> MGTIN["input/"] + MGT --> MGTOUT["output/"] + + LEG --> LEG1["licenses/"] + LEG --> LEG2["compliance/"] + LEG --> LEGIN["input/"] + LEG --> LEGOUT["output/"] + + ENG --> ENGIN["input/"] + ENG --> ENGOUT["output/"] + ENG --> E01["01_concept/"] + ENG --> E02["02_design/"] + ENG --> E03["03_make/"] + ENG --> E04["04_validation/"] + ENG --> E05["05_release/"] + + E01 --> E01A["requirements/"] + E01 --> E01B["moodboards/"] + E01 --> E01C["adr/"] + + E02 --> E02A["electronics/"] + E02 --> E02B["mechanical/"] + E02 --> E02C["firmware/"] + E02 --> E02D["wear_parts/"] + + E03 --> E03A["bom/"] + E03 --> E03B["assembly_guide/"] + E03 --> E03C["fabrication_files/"] + E03C --> E03C1["3d_print/"] + E03C --> E03C2["laser_cut/"] + E03C --> E03C3["pcb/"] + + E04 --> E04A["safety/"] + E04 --> E04B["test_reports/"] + + E05 --> E05A["oshwa_certification/"] + E05 --> E05B["media/"] + + ROOT --> STW["40_stewardship/"] + ROOT --> USG["50_usage/"] + + STW --> STW1["01_maintenance/"] + STW --> STW2["02_repair/"] + STW --> STW3["03_recovery/"] + + USG --> USG1["example/"] + + style ROOT fill:#f5f5f5,stroke:#999 + style MGT fill:#dbeafe,stroke:#3b82f6 + style LEG fill:#fef9c3,stroke:#eab308 + style ENG fill:#dcfce7,stroke:#22c55e + style E01 fill:#eff6ff,stroke:#93c5fd + style E02 fill:#eff6ff,stroke:#93c5fd + style E03 fill:#eff6ff,stroke:#93c5fd + style E04 fill:#eff6ff,stroke:#93c5fd + style E05 fill:#eff6ff,stroke:#93c5fd + style MGTIN fill:#fde8e8,stroke:#f87171 + style MGTOUT fill:#d1fae5,stroke:#34d399 + style LEGIN fill:#fde8e8,stroke:#f87171 + style LEGOUT fill:#d1fae5,stroke:#34d399 + style ENGIN fill:#fde8e8,stroke:#f87171 + style ENGOUT fill:#d1fae5,stroke:#34d399 + style STW fill:#fef3c7,stroke:#f59e0b + style STW1 fill:#fef9c3,stroke:#fbbf24 + style STW2 fill:#fef9c3,stroke:#fbbf24 + style STW3 fill:#fef9c3,stroke:#fbbf24 + style USG fill:#f3e8ff,stroke:#a855f7 +``` diff --git a/mod/designish/definition.csv b/mod/designish/definition.csv new file mode 100644 index 0000000..0eedf23 --- /dev/null +++ b/mod/designish/definition.csv @@ -0,0 +1,89 @@ +Path,Normative,Tracked,Generated,Module,ArbitraryContent,Tags,Indicativeness,Variations,Regex,Description,Sample Content +LICENSES/,true,true,false,false,false,,0.2,LICENSES,,REUSE license files (preferred over single LICENSE file), +LICENSES/CERN-OHL-S-2.0.txt,false,true,false,false,-,license,0,,[^/]+\.txt,,https://cern-ohl.web.cern.ch/ +LICENSE,true,true,false,false,-,license,0,,(?i)(LICEN[SC]E|COPYING)(\.[^/]+)?(\.(txt|md|rst))?,Single project-wide license file (optional fallback), +README.md,true,true,false,false,-,,0,,(?i)README(\.(txt|md|rst))?,, +okh.toml,true,true,false,false,-,,0,,okh\.(toml|ya?ml|json|ttl|rdf),Open Know-How manifest — machine-readable project metadata for crawlers and indexers,https://gitlab.com/OSEGermany/ohloom/-/raw/master/okh.toml +10_management/,true,true,false,false,false,,0.9,management,,The Studio — administrative hub: roadmap; meetings; stakeholders, +10_management/01_roadmap/,true,true,false,false,true,,0.5,roadmap,,Visual timelines and milestones, +10_management/01_roadmap/roadmap.md,false,true,false,false,-,,0,,.+\.md,, +10_management/02_meetings/,true,true,false,false,true,,0.5,meetings,,Community sync notes; files named YYYY-MM-DD_topic.md, +10_management/02_meetings/2026-03-26_kickoff.md,false,true,false,false,-,,0,,[0-9]{4}-[0-9]{2}-[0-9]{2}_[^/]+\.md,, +10_management/03_stakeholders/,true,true,false,false,true,,0.4,stakeholders,,Map of contributors and community members, +10_management/03_stakeholders/contributors.md,false,true,false,false,-,,0,,.+\.md,, +10_management/input/,true,true,false,false,true,,0.3,input,,Incoming briefs; requests and information received from stakeholders, +10_management/output/,true,true,false,false,true,,0.3,output,,Approved plans; decisions and mandates passed to engineering phases, +20_legal/,true,true,false,false,false,,0.8,legal,,The Safety Net — open source licensing and compliance, +20_legal/licenses/,true,true,false,false,true,,0.6,licenses,,License documents per domain (hardware; firmware; documentation), +20_legal/licenses/hardware_CERN-OHL-S-2.0.txt,false,true,false,false,-,license,0,,.+\.txt,,https://cern-ohl.web.cern.ch/ +20_legal/licenses/firmware_GPL-3.0.txt,false,true,false,false,-,license,0,,.+\.txt,,https://www.gnu.org/licenses/gpl-3.0.txt +20_legal/licenses/docs_CC-BY-SA-4.0.txt,false,true,false,false,-,license,0,,.+\.txt,,https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt +20_legal/compliance/,true,true,false,false,true,,0.5,compliance,,Certification documents and test reports (CE; FCC; etc.), +20_legal/compliance/ce_declaration.pdf,false,true,false,false,-,,0,,.+\.pdf,, +20_legal/input/,true,true,false,false,true,,0.3,input,,Draft agreements; policy references and incoming compliance requests, +20_legal/output/,true,true,false,false,true,,0.3,output,,Signed licenses; cleared compliance documents and legal approvals, +30_engineering/,true,true,false,false,false,,0.9,engineering,,The Creative Pipeline — 5-phase design and production process, +30_engineering/01_concept/,true,true,false,false,false,,0.8,concept,,The Sketchbook — requirements; moodboards; architecture decisions, +30_engineering/01_concept/requirements/,true,true,false,false,true,,0.5,requirements,,Functional and non-functional requirements, +30_engineering/01_concept/requirements/requirements.md,false,true,false,false,-,,0,,.+\.md,, +30_engineering/01_concept/moodboards/,true,true,false,false,true,,0.4,moodboards,,Visual explorations; sketches and block diagrams, +30_engineering/01_concept/moodboards/moodboard-01.png,false,true,false,false,-,,0,,.+\.(png|jpg|webp|svg),, +30_engineering/01_concept/moodboards/block-diagram.svg,false,true,false,false,-,,0,,.+\.svg,, +30_engineering/01_concept/adr/,true,true,false,false,true,,0.7,adr|decisions,,Architecture Decision Records; files named NNN_decision-topic.md, +30_engineering/01_concept/adr/001_why-freecad.md,false,true,false,false,-,,0,,[0-9]+_[^/]+\.md,, +30_engineering/02_design/,true,true,false,false,false,,0.8,design,,The Workbench — editable source files organised by discipline, +30_engineering/02_design/electronics/,true,true,false,false,true,,0.7,electronics,,Schematics and PCB layouts (KiCad), +30_engineering/02_design/electronics/main.kicad_pro,false,true,false,false,-,,0,,.+\.kicad_pro,, +30_engineering/02_design/electronics/main.kicad_sch,false,true,false,false,-,,0,,.+\.kicad_sch,, +30_engineering/02_design/electronics/main.kicad_pcb,false,true,false,false,-,,0,,.+\.kicad_pcb,, +30_engineering/02_design/mechanical/,true,true,false,false,true,,0.7,mechanical,,3D CAD models and 2D drawings (FreeCAD; STEP; SVG), +30_engineering/02_design/mechanical/case.FCStd,false,true,false,false,-,,0,,.+\.(FCStd|fcstd),, +30_engineering/02_design/mechanical/case.step,false,true,false,false,-,,0,,.+\.(step|stp),, +30_engineering/02_design/mechanical/drawing-01.svg,false,true,false,false,-,,0,,.+\.svg,, +30_engineering/02_design/firmware/,true,true,false,false,true,,0.6,firmware,,Firmware sources — the brain of the hardware, +30_engineering/02_design/firmware/Makefile,false,true,false,false,-,,0,,Makefile,, +30_engineering/02_design/firmware/main.c,false,true,false,false,-,,0,,.+\.[ch],, +30_engineering/02_design/firmware/config.h,false,true,false,false,-,,0,,.+\.h,, +30_engineering/02_design/wear_parts/,true,true,false,false,true,,0.6,wear_parts,,Components designed for frequent replacement — consumables and high-wear parts, +30_engineering/02_design/wear_parts/wear-part-01.FCStd,false,true,false,false,-,,0,,.+\.(FCStd|fcstd|step|stp|stl|3mf),, +30_engineering/02_design/wear_parts/wear-parts.md,false,true,false,false,-,,0,,.+\.md,, +30_engineering/03_make/,true,true,false,false,false,,0.9,make,,The Factory — everything needed to build one unit, +30_engineering/03_make/bom/,true,true,false,false,false,,0.7,bom,,Bill of Materials, +30_engineering/03_make/bom/bom.csv,true,true,false,false,-,bom,0.5,,bom\.csv,"Machine-readable Bill of Materials, source",https://gitlab.com/OSEGermany/ohloom/-/raw/master/sBoM.csv +30_engineering/03_make/bom/bom.md,true,true,false,false,-,bom,0.3,,bom\.md,"Human-readable Bill of Materials, source", +30_engineering/03_make/assembly_guide/,true,true,false,false,false,,0.8,assembly_guide,,Step-by-step assembly instructions (IKEA-style manual), +30_engineering/03_make/assembly_guide/guide.md,true,true,false,false,-,,0.3,,guide\.md,Top-level assembly guide entry point, +30_engineering/03_make/assembly_guide/step-01/,false,true,false,false,true,,0,,step-[0-9]+/,,One directory per assembly step, +30_engineering/03_make/assembly_guide/step-01/step-01.md,false,true,false,false,-,,0,,.+\.md,, +30_engineering/03_make/assembly_guide/step-01/step-01.png,false,true,false,false,-,,0,,.+\.(png|jpg|webp),, +30_engineering/03_make/fabrication_files/,true,true,false,false,false,,0.8,fabrication_files,,Ready-to-manufacture output files (STL; DXF; Gerbers), +30_engineering/03_make/fabrication_files/3d_print/,true,true,false,false,true,,0.7,3d_print,,3D printing files (STL; 3MF), +30_engineering/03_make/fabrication_files/3d_print/case.stl,false,true,false,false,-,,0,,.+\.(stl|3mf),, +30_engineering/03_make/fabrication_files/laser_cut/,true,true,false,false,true,,0.7,laser_cut,,Laser cutting files (DXF; SVG), +30_engineering/03_make/fabrication_files/laser_cut/panel.dxf,false,true,false,false,-,,0,,.+\.(dxf|svg),, +30_engineering/03_make/fabrication_files/pcb/,true,true,false,false,true,,0.7,pcb,,PCB manufacturing files (Gerbers; drill; BoM; CPL), +30_engineering/03_make/fabrication_files/pcb/main-gerbers.zip,false,true,false,false,-,,0,,.+-gerbers\.zip,, +30_engineering/03_make/fabrication_files/pcb/main-bom.csv,false,true,false,false,-,bom,0,,.+-bom\.csv,, +30_engineering/04_validation/,true,true,false,false,false,,0.9,validation,,The Lab — safety; testing and circularity, +30_engineering/04_validation/safety/,true,true,false,false,true,,0.7,safety,,Risk analysis (FMEA) and safety documentation, +30_engineering/04_validation/safety/fmea.md,false,true,false,false,-,,0,,.+\.md,, +30_engineering/04_validation/test_reports/,true,true,false,false,true,,0.7,test_reports,,Prototyping and validation test reports; named YYYY-MM-DD_topic.md, +30_engineering/04_validation/test_reports/2026-03-26_prototype-v1.md,false,true,false,false,-,,0,,[0-9]{4}-[0-9]{2}-[0-9]{2}_[^/]+\.md,, +30_engineering/05_release/,true,true,false,false,false,,0.8,release,,The Gallery — sharing the finished project with the world, +30_engineering/05_release/oshwa_certification/,true,true,false,false,true,,0.6,oshwa_certification,,Open Source Hardware compliance evidence and OSHWA UID, +30_engineering/05_release/oshwa_certification/oshwa-uid.md,false,true,false,false,-,,0,,.+\.md,, +30_engineering/05_release/media/,true,true,false,false,true,,0.6,media,,Hero shots; tutorial videos and press kit, +30_engineering/05_release/media/hero-shot.jpg,false,true,false,false,-,,0,,.+\.(jpg|png|webp),, +30_engineering/05_release/media/tutorial.webm,false,true,false,false,-,,0,,.+\.(webm|mp4),, +30_engineering/05_release/media/press-kit.md,false,true,false,false,-,,0,,.+\.md,, +40_stewardship/,true,true,false,false,false,,0.8,stewardship,,Circularity — ongoing repair; maintenance and end-of-life recovery [NEW], +40_stewardship/01_maintenance/,true,true,false,false,true,,0.5,maintenance,,Cleaning; calibration and upkeep logs, +40_stewardship/01_maintenance/maintenance-log.md,false,true,false,false,-,,0,,.+\.md,, +40_stewardship/02_repair/,true,true,false,false,true,,0.6,repair,,Troubleshooting guides and disassembly instructions, +40_stewardship/02_repair/repair-guide.md,false,true,false,false,-,,0,,.+\.md,, +40_stewardship/02_repair/disassembly-guide.md,false,true,false,false,-,,0,,.+\.md,, +40_stewardship/03_recovery/,true,true,false,false,true,,0.5,recovery,,Recycling paths; material recovery and upcycling ideas, +40_stewardship/03_recovery/recycling.md,false,true,false,false,-,,0,,.+\.md,, +50_usage/,true,true,false,false,false,,0.6,usage,,Implementation examples and use-cases, +50_usage/example/,true,true,false,false,true,,0.5,example,,Settings; samples and concrete use-case examples, +50_usage/example/example.md,false,true,false,false,-,,0,,.+\.md,, diff --git a/mod/designish/definition.csv.license b/mod/designish/definition.csv.license new file mode 100644 index 0000000..cb55ea9 --- /dev/null +++ b/mod/designish/definition.csv.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2026 OSH Dir Std Contributors +SPDX-FileCopyrightText: 2026 Benjamin Götze +SPDX-License-Identifier: GFDL-1.3-or-later