|
Location: Separate Documentation repository in a GitLab group project. That way you have history, notes, membership, ownership, and processes (templates, merge permissions, reviewers)! This can also be included as a submodule in your software repo. And can be used to read/edit by devs in their chosen IDE, or R/W on GitLab via html, or can generate static html documentation via pipelines. Oh, and you can build pipelines to generate html outputs for different use cases, and perform checks, run scripts, etc. Framework: Choose a framework, like Arc42 for general layout as a good starting point. Remember you have company, quality, project, program, product, process, user, internal how-to's, etc. documentation types not just... user-guides and systems-architecture..so this will be dependent on your org/product. Go for MVP and 80-20. Plan: Write a plan as part of the documentation that details all of these facets and rules so all contributors understand it. Formats: drawio.svg for complex diagrams, mermaid for simple diagrams or if important to change manage like code, asciidoc for complex documents, markdown for most/simpler docs. Tables in csv or asciidoc. Images in svg, or png. Everything aforementioned renders on GitLab. Other rules: Automate everything possible to reduce [manual] documentation. Use text/code vs proprietary formats. You can get more and more complex with the tech writers, dev, ops, systems, all under one roof and coordinating documentation and pipeline scripting. |