Skip to content

DI Documentation

Proposal: Concept & Pilot

There is a growing need for a common and simple solution regarding documentation within our Digital Infrastructure department.
This proposal has been made by Jente Buijs (TCI), Maarten van Gompel (TT) and Marielle Veldhuis (TP) in an attempt to find a solution that can accommodate the usecases of all different teams and go hand in hand with the decisions of our DI-documentation-workgroup. We're aiming for a broad supportbase within DI to ensure proper implementation of the chosen method.

Concept

  • Documentation written in Markdown files, kept in Git.
  • Hosted for (both internal and external) users as static HTML-websites, via a static site generator (mkdocs)
  • Main git repository is private
  • We want part of the site lockable for an internal audience whereas the default is public
  • Deployment in Kubernetes with CI/CD-pipeline
  • Markdown-files from other repos/platforms can be included as git submodules (decentralisation)
    • ... so documentation may live elsewhere and can still be presented on the site
  • No platform/editor lock-in
  • Git ensures proper version history and attribution (but no real-time collaborative editing)

Pilot

  • DI Documentation website: https://documentatie.di.huc.knaw.nl/
  • Main git source repository
    • private
    • (see here for more information)
    • CI/CD pipeline automatically deploys upon new commits
  • Section-suggestions:
    • General guidelines and best practises e.g. GIT Best Practices, Software Quality Guidelines, K8s, guidelines to documentation editing
    • Instructions/Manuals for (new) DI-employees e.g. How to reuse this pipeline to host documentation for your endusers
    • DI-wide decisionlist with links to Meeting Notes/elaborating files
      e.g. MT accepting this proposal on 04-06-2025
    • Teams: Overview/introduction per team
    • Projects: Overview/introduction per project
    • Working Groups: Overview/introduction per project
    • Software and Services: Overview/introduction of software services (linking to https://tools.huc.knaw.nl/)
  • Use of this di-documentatie set-up is a convenience and not a requirement; if you have good reasons to host and deploy documentation elsewhere, then feel free! (and consider just linking to it from the documentatino site). Notable examples of things that live elsewhere are: software-specific documentation (e.g. on platform like readthedocs, docs.rs), automated API references (doxygen, sphinx, etc), project websites. Our aim is to offer a common and largely decentralised method everybody can fall back to.

Goals

  • Prevent (both DI- and institute-)employees from finding own solutions that
    1) Create more clutter/confusion and support-/maintenance-workload
    2) Make it harder and harder to agree on a common solution
  • Clarity on what to find where (opposed to scattered information in confluence/slack/email etc)
  • More insight into other teams' activities and common interests/objectives within DI to stimulate collaboration
  • Better communication between DI and institutes/endusers
  • Basic building blocks that allow for limited dependence on external platforms
  • Flexible aggregation of "documentation-islands" to websites for certain target-audiences (without having to move repositories to other a central platform)

Suggestions for further discussion

  • DI-wide naming conventions and procedures around documentation-repositories
  • How to enforce made decisions concisely to avoid deterioration through time
  • Obligatory introduction.md in projects to allow for a DI-wide-overview?
  • Potential future feature: Web-based WYSIWYG editor for less tech-savy colleagues (e.g. https://decapcms.org/)