general:project_documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
general:project_documentation [2025/07/21 10:45] – removed - external edit (Unknown date) 127.0.0.1general:project_documentation [2025/07/22 08:24] (current) – patrick.kahr
Line 1: Line 1:
 +====== Project Documentation ======
 +
 +This guide describes our general approach towards documentation. On a high level, we distinguish several types of documentation:
 +
 +  * Dynamic Documentation
 +  * Project Specific Documentation
 +
 +===== Dynamic Documentation =====
 +
 +Dynamic documentation includes notes and docs
 +
 +  * whose scope is not well defined
 +  * that require frequent changes
 +  * that don't have a clear //**definition of done**//, but are rather a snapshot of certain point in time
 +  * that do not require semantic versioning or a browse-able history of older versions
 +
 +An example for such a type of documentation are the IT inventory, or the usage instructions for the coffee machine. Keeping a list of devices such as servers and network routers requires constant updates to reflect the most recent changes. Since the IT infrastructure undergoes continuous development, it does not make sense to think in terms of fixed releases. (If a device breaks, it needs to be replaced, possibly by another type of device that has a slightly different configuration).
 +
 +We keep this type of documentation in a Wiki as it can be quickly edited.
 +
 +====== Our Wikis ======
 +
 +We organize content into separate department-specific wikis:
 +  * [[https://wiki.ops.rekonas.com|Operations]]
 +  * [[https://wiki.rd.rekonas.com|Research & Development]]
 +  * [[https://wiki.prod.rekonas.com|Production]]
 +
 +===== Project-specific Documentation =====
 +
 +On the other hand we have documentation for specific projects (software, hardware, combined, ...). In contrast to the examples before, these project follow a different lifecycle and therefore need a different approach when it comes to documentation. 
 +
 +To improve project documentation in general we aim to:
 +
 +  * create consistent templates
 +  * define a standardized workflow
 +  * provide infrastructure to project contributors and users
 +
 +On a high level, we can define several groups of documents that are necessary to fully document a project.
 +
 +==== Core Documents ====
 +
 +=== System Documentation ===
 +The developer's technical lifeline:
 +
 +  * Technical Requirements & Dependencies
 +  * Architecture documentation: System structure and reasoning
 +  * Code documentation: API docs, inline comments, specifications
 +  * Setup and deployment guides: Environment configuration
 +  * Database schemas and data flow diagrams
 +  * User documentation
 +  * Adjacent projects
 +
 +=== Process Documentation ===
 +The ***How we work*** knowledge:
 +
 +  * Responsibilities
 +  * Documentation guidelines
 +  * Coding standards and testing procedures
 +  * Benchmarking
 +  * Git workflows and branching strategies
 +  * Code review processes
 +  * Release procedures and deployment pipelines
 +
 +=== Key strategic Documents ===
 +
 +  * Product Requirements Document (PRD): Team roles, business objectives, user stories, acceptance criteria
 +
 +==== General Worflow ====
 +
 +The workflow should serve the main three goals of Creation, Maintenance, and Discoverability.
 +
 +==== Creation ====
 +
 +**Bootstrapping**: When starting a new project, the workflow in general looks like this:
 +
 +{{:general:workflow.png?400|}}
 +
 +  -   Iterative project brainstorming (organized by project owner)
 +  -   Project Setup (Docs, Code, Hardware, other dependencies)
 +  -   Project planning setup (collaborative)
 +
 +//**Tool**//: Use the collaborative Sketchpad at [[https://sketch.rekonas.com|sketch.rekonas.com]]
 +
 +You can use the following template to get started: [[https://sketch.rekonas.com/E9x2lhChRIOgP-eTI10bMg#]]
 +
 +**Progress Documentation**: Planning documentation milestones is an integral part of project planning. It is up to the project owner to decide what level of documentation is required at a certain milestone.
 +
 +**Project organization summary**: Provide a short summary of project documentation setup (visual and written) that can serve as an inspiration for future projects.
 +
 +==== Maintenance ====
 +
 +**Keep Docs in Sync**: Make sure that the project documentation is not lagging behind your project releases
 +
 +**Docs as integral part of project**: Make documentation updates part of Definition of Done. It is up to the project owner to decide the exact scope the documentation at a specific stage of the project.s
 +
 +==== Discoverabilty ====
 +
 +**Single landing page**: The project docs should serve a single entry point to all resources regarding this project such as:
 +
 +  * Getting started instructions
 +  * Architecture Overview
 +  * API References
 +  * Deployment Guides
 +  * Contributor Guidelines
 +
 +**Project Directory**: Our documentation site will provide an overview over all existing projects, making it easier to find other content.
 +
 +==== Implementation ====
 +
 +To help with the creation of documentation, we provide a setup including a template.
 +
 +=== Stack ===
 +
 +Our solution is based on:
 +
 +  * MkDocs (Material)
 +  * Gitea Template
 +  * Gitea Action
 +  * Docs website (auto-deploy)
 +
 +=== Project Structure ===
 +
 +The template is already populated with a basic structure that should help us reach a certain level of consistency between the docs for different projects:
 +
 +1. Getting Started: Setup and Quickstart guides
 +2. Architecture: Explains the architecture of the project
 +3. Components: Details about individual components
 +4. Deployment: Explains hos to build, package and release the project
 +5. Contributing: This is where all the process documentation for the project goes
 +6. User Documentation: User manuals
 +
 +
 +=== Template & Tutorial ===
 +
 +To get started easily a template is provided together with a tutorial:
 +
 +
 +  * Gitea Template: https://code.rekonas.com/rekonas/docs-template
 +  * Online Version: https://docs.rekonas.com/template/
 +
 +Before starting a new project, it is recommended to have a look at the Tutorial: https://docs.rekonas.com/template/0.1.2/Help/Tutorial/
 +
 +