aktin / aktin/aktin-github-handbook

Rework AKTIN DWH User Documentation

Abierto
#1 0 comentarios 0 reacciones 3 asignados Reclamado por @akomii Ver en GitHub
documentation
Lenguaje dominante
Sin datos de lenguaje
Estrellas
0
Forks
0
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

## Goal

Replace the two existing user documentation sites of the AKTIN Data Warehouse (DWH) with one VuePress site in this repository, published on GitHub Pages.

Today the documentation lives in two repositories as Maven sites (`src/site/markdown/`) and is served from the AKTIN website:

- https://github.com/aktin/dwh-setup/tree/master/src/site/markdown (installation, updates, configuration, changelog)
- https://github.com/aktin/dwh-import/tree/main/src/site/markdown (import interfaces: CDA, HL7 FHIR, IHE XDS.b, demo server)

In addition, several how-to and troubleshooting articles exist only as Confluence exports (PDF and Markdown). All of this material has already been copied into `legacy/` (see #2).

## Result we want

- One site, one repository, one deploy pipeline.
- Content in German, in the style already used in `docs/install/` and `docs/update/`.
- Readers are DWH administrators at hospitals, not developers. Every page must be usable without reading source code.
- Site is reachable on GitHub Pages and is rebuilt automatically on every push to `main`.

## How to work in this repository

- All work happens on branch `dev`. Open a pull request against `main` when a sub-issue is finished. `main` is what gets deployed.
- Requirements: Node.js 22 and npm.
- Run `npm install` once, then `npm run docs:dev` starts a local server at http://localhost:8080 with hot reload.
- `npm run docs:build` produces the static site in `docs/.vuepress/dist/`. Run it before opening a pull request. Dead links and missing images show up as warnings there.
- Content lives in `docs//*.md`. Images belong next to the page in `docs//images/`.
- The sidebar is defined in `docs/.vuepress/config.js`. A new page only shows up after it is added there.
- Links used on many pages (support mail, links between pages) are defined once in `docs/.vuepress/_refs.md` and used as `[Text][ref-name]`.
- Version numbers come from `.env` and are used in Markdown as `{{ $theme.versions.dwh }}`. Never hardcode a DWH or Ubuntu version.
- Layout customisation (footer etc.) lives in `docs/.vuepress/layouts/Layout.vue`, which extends the default theme layout.

Background reading:
- VuePress guide https://vuejs.press/guide/
- default theme reference https://ecosystem.vuejs.press/themes/default/

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.