Docmd Software-Doku: Schreiben, Designen und Veröffentlichen

Du willst lernen, wie Du gelungene Doku mit Docmd erstellst?

Hier ist Dein Guide!

Starten wir!

Warum Doku (mit Docmd) schreiben?

Du brauchst eine neue Software? Software kostet 0 €, aber Doku und Support kostet 10.000 € – Viele Tech-Unternehmen machen ihr Geld nicht mehr mit der Software.

Sie leisten den Support für Privatpersonen und Unternehmen, damit diese in allen Situation gut läuft. Auch wenn Du nicht kommerziell unterwegs bist, kann Deine Open Source Lösung nur brillieren, wenn die Leute wissen, wie man das Produkt nutzen kann.

• Selbstschutz: Dokumentation hilft Dir dabei, Dein Projekt besser zu verstehen und Deinem zukünftigen Ich Deinen Schei… zu erklären. Was Dir heute einleuchtend erscheint und frisch gecodet ist, ist in 3 Monaten der Graus von Code, den keiner versteht. Es gibt im Code und den Modulen so viele Abhängigkeiten, dass Du schnell die Übersicht verlierst.
• Nutzungsanleitung für Kunden / Interessierte: Doku soll neue Nutzern dabei helfen, die Software zu installieren, zu nutzen und ihre Daten zu migrieren. Eine komplexe Software ohne Anleitung ist nichts wert. Gute Benutzeroberflächen können den Dokuaufwand reduzieren, aber Du solltest erklären, was der Nutzer an Eingaben tätigen soll, wie die Verarbeitung aussieht und was für Ergebnisse in welchem Format zu erwarten sind.
• Mitstreiter finden: Gute Doku zieht Mitstreiter an, die mit Dir programmieren wollen. Wer den Entwicklungsprozess versteht, hat überhaupt die Chance mitzuentwickeln. Nicht jeder Programmierer ist bereit, Deinen gesamten Code zu reverse-engineeren, um voranzukommen.

Warum Docmd nutzen?

• Leicht: Docmd besteht auf einem einzigen Node-js Modul und wandelt Deine Markdown Dateien in statisches HTML und CSS um. Etwas JavaScript ist dabei, aber es sind nur 25 KB an Speicher notwendig.
• Alles an notwendigen Features vorhanden: Eine Doku sollte immer diese Features haben – eine Suche, Überschriften, Untergliederungen, Übersetzungen, Links, Übesetzungen
• Kein Schnickschnack: Du musst keinen komplexen Server aufsetzen. Die HTML-Dateien laufen auf jedem Webserver ohne weitere Konfiguration.

Tutorial

Initialisierung – Wie starte ich?

Erstelle einen Ordner und lege ein Git-Repo an.

Installiere die Node.js LTS über das Programm NVM, um Pakete aus dem Node Universum zu laden.

Linux:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

Windows:

Downloade dir das hier: https://github.com/coreybutler/nvm-windows

Installiere die Software NVM, um zwischen verschiedenen Node-Versionen zu wählen und schnell zu wechseln

nvm install 24

Installiere Docmd in dem Ordner, in dem Du starten willst.

npx @docmd/core dev

Wähle Deinen Präferenzen bei dem Menü aus.

Schreiben – Was muss ich beim Tippen beachten?

Jetzt erstellst Du alle Deine Markdown Dateien in dem Ordner „docs” und strukturierst diese so, wie es für Dich Sinn ergibt.

Markdown besteht aus normalen Text und einigen Tags, die eine Formatierung ermöglichen.

Die Standard Markdown Tags versteht Docmd:

Überschrift    

# H1
## H2
### H3

Fett      **Fettgedruckter Text**
Kursiv    *Kursivgedruckter Text*
Zitat     > Zitat

Aufzählung   

1. Erster Punkt
2. Zweiter Punkt
3. Dritter Punkt

Aufzählung    

- Erster Punkt
- Zweiter Punkt
- Dritter Punkt

Code    `code`
Horizontale Linie    ---

Link    [Titel](https://www.example.com)
Bild    ![Alternativtext](image.jpg)

Weitere Befehle zum normale Markdown findest Du hier: https://www.markdownguide.org/cheat-sheet/

Docmd erlaubt noch weitere Tags, mit der Du weitere Aspekte formatieren kannst.

- [ ] Ein Aufgabe
- [x] eine beendete Aufgabe

Eine normaler Text und dann brauche ich eine Fußnote.[^1]

[^1]: Ganz großer Quatsch

::: card "Eine Karte" icon:zap
Noch mehr Karteninhalt
:::

Hier empfehle ich die Docu von Docmd selbst https://docs.docmd.io/content/syntax/advanced/

Inhalte – Was gehört in eine Docu?

Was braucht eine gute Docu? Beginne die folgenden Abschnitte zu beschreiben:

• Quick Start: Wie kann ein Newbie die Software in 5 Minuten laufen lassen?
• Installation: Welche Formen der Installation gibt es? Welche Plattformen unterstützt die Software?
• Verwendung von XY: Wie kann man die Features der Software nutzen? Welche Eingaben sind notwendig?
• Entwicklung: Wenn ein paar andere Verrückte mit entwickeln wollen, brauchen diese Instruktionen, wie Du Deine Entwicklungssetup gestaltet hast.
• Verwendung User Interface: Grafische Nutzeroberflächen sind nicht immer eindeutig und Tipps und Tricks haben bisher keinem geschadet.
• Schnittstellen / Command Line Interface: Wenn Deine Software noch mehr Interaktionspunkte bietet, beschreibe diese!
• Einstellungen / Parameter: Wie kann der Nutzer die Software an seine Bedürfnisse anpassen?
• Lizenz: Wie darf die Software verwendet werden? Deutsches Urheberrecht, MIT, GPLv3, BSD Lizenz?

Kompilieren – Wie wird daraus eine Webseite?

Docmd kannst Du lokal oder in der Pipeline kompilieren.

docmd build

In Jenkins kannst Du einen Pipeline-Schritt hinzufügen. Dazu musst Du in den richtigen Ordner skippen und dort mit NPM docmd installieren.

stage('Compile docu') {
    steps {
        dir('frontend') {
            sh 'npm install -g @docmd/core'
            sh 'cd docs && docmd build'
        }
    }
}

… oder mit Docker bauen lassen. Hier eignet sich Node-26 Docker als Bau-Container und als Ausführungsumgebung reicht ein NGINX unprivileged aus. Wir hosten nur statische Dateien und brauchen keine Zusatzberechtigungen.

FROM node:26-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm install npm -g 
RUN npm install -g @docmd/core
RUN npm cache clear --force
RUN npm install --prefer-offline --no-audit --progress=false
COPY . .
RUN cd docs && docmd build

FROM nginxinc/nginx-unprivileged:stable-alpine-slim AS production
COPY --from=build /app/docs/site /usr/share/nginx/html/docu
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]

Diese NGINX Konfiguration (nginx.conf) stellt die Doku zur Verfügung.

pid /tmp/nginx.pid; 
events { 
  worker_connections  1024;  ## Default: 1024 
} 
 
http { 
 
    ## use mime types 
    include /etc/nginx/mime.types; 
    
     server { 
        
        listen 8080; 
 
        location /docu/ {
            alias /usr/share/nginx/html/docu/;
            index index.html;
            try_files $uri $uri/ /docu/index.html?$query_string;
        }
    } 

} 

Veröffentlichen – Wie kann ich es publizieren?

Jetzt kannst Du die Webseite kopieren /docs und zu einem Webhosting-Dienst 1:1 hochladen oder den Docker Container starten und den Port publizieren.