Documentation QA Activities 2023

Owned by Uwe Wahser
Last updated: Apr 18, 2023 by Marco Kalin
4 min read

Collection of tasks to improve openIMIS Documentation

Public Facing

General

Users

  • Improve user documentation /

    • Update user documentation to current cooperate design (use new logo)

    • Links towards the Wiki need to be checked (e.g. “openIMIS Install documentation”)

    • Ensure coherency of the linkage between the user documentation and other platforms (like the Wiki or the webpage)

  • Update

    • Remove usage of featured FAQ lists outside of the website sandbox

    • Move to Sandbox

Implementers

  • Validate and Integrate into

  • Update to allow people that are interested to quickly setup the current version in the supported environment (Linux & PostgreSQL)

    • Variations as “Implementers Experience reports” as link out from the standard installation instruction e.g. “see other

  • Clean up naming: “modular” is default case and doesn’t need to be especially designated as such for the purpose of , “legacy” is special case, its content need to be updated/removed/archived to reflect the new reality - E.g. in - This also needs to be reflected in documentation within the (GitHub) repositories

  • Validate and Integrate into

    • Update

  • Integrate further mature/non-development content into

  • Describe Configuration/Customization (per module) in ↔︎ Dev Committee #288

  • Create “How to migrate from Legacy to Modular” (see )

  • Create “How to update from version / release x to version / release y” tutorial

  • Validate and Document Testing Scenarios ↔︎ Dev Committee #223

  • Validate and Integrate into

  • Validate and Integrate into

  • Validate and Integrate into

  • Validate and Integrate into

  • Validate and Integrate into

  • Validate and Integrate into

Developers

Development guidelines

  • Update for

  • Update for

  • Create “Technical Requirements” page and fill with content e.g.

  • Validate and Integrate into

    • Validate

    • Validate

    • Validate

    • Integrate into

    • Integrate “Automated CI testing" of into

  • Validate and integrate into

  • Validate YouTube content for / current development ↔︎ Dev Committee #176

    • Merge YT-Playlists and

  • Validate and update Functional specification / Technical documentation

  • Integrate code documentation in Wiki (see )

  • Setup a “Source Code Opportunities” page where software solutions of projects like , the solution of Bluesquare in Nepal or other prototypes / proof of concepts can be put, maintained and referred to, to be taken up and being further developed

Github

  • Clarify distribution of documentation between GitHub repo and Wiki and remove redundancies

  • Clarify distribution of release notes between GitHub repo and Wiki and remove redundancies

  • Mark/Remove/Hide deprecated GitHub repos

  • Provide license information in every repository

Architecture

  • Rework/create documentation of modular architecture

  • Reorganize structure in and create overview according to / / (slide 12) ↔︎ Dev Committee #105

  • Create dependency graph for openIMIS modules / repos in

  • Validate and Integrate (e.g. ) into

  • Validate and Integrate into

  • Validate and Integrate into

  • Validate and Integrate into

  • Validate and Integrate into

  • Update each module in

    • Create a link to the code documentation ↔︎ Dev Committee #260

    • Clarify options for configuration and/or customization of a module ↔︎ Dev Committee #274 and #288

  • Validate and Integrate finished Projects from into (Architecture)

Release

  • Document Release Management into

    • Step by step deliverables / check-list (integrate pull-requests, update doku, update modules overview) ->

  • Update for and optimize accessibility

  • Integrate into

  • Merge / move / clean up into

  • Setup / optimize a documentation update process (checklist) to ensure the documentation improves in a timely and parallel way

Documentation Methodology

  • How to document architecture: Graphics: repository for architecture etc done with draw.io

  • Re-organize first level children of e.g. create and move content into our Technical Knowledge Base as “How-to”

  • Validate and Integrate further mature/not-in-development content into

  • Standardize naming in our Technical Knowledge Base “How to” etc. …

  • Standardize naming in substructure explicitly “openIMIS” everywhere or nowhere

  • Include Domain Knowledge into

  • Setup Process for Transform Product Owner / Incubator Knowledge to

  • Setup Framework to Improve Recording, Documentation and Publishing of Webinars

    • Enable the process to be started externally (e.g. per Jira queue)

Internal Documentation

Under Maintenance Contract

  • Sandbox Server access / root account

  • Consolidate server hosting credentials, migration of DNS host and access sharing strategies -> Server Administration & Accounts

  • Clean up

  • Keypass keyrings:

    • Admin (on internal teams channel)

    • Others on demand

 

GIZ internal

  • Server contract login (Keypass keyring)

  • Web-page - Wiki links:

  • Remove / document / avoid content redundancies between web and wiki

  • Make sure the transition from web to Wiki is smooth (especially for first time users)

  • Clean up Teams channels (List, messages, export)

  • Analyze back-links from Wiki to Web - e.g. (and other implementations) refers to on the web

  • Publish relevant Events on Web

  • Remove and other redundant content after launch of new version of Web

Guiding Principles

  • Separate static from temporal content

  • Remove and avoid redundancies

Taskforces

Taskforce

Involved Parties

Meetings

Taskforce

Involved Parties

Meetings

Release checklist, Server Doc (T1)

Improving technical documentation, ensuring sustainable operations

STPH, GIZ

Weekly Wed. 11-12pm

 

Did you encounter a problem or do you have a suggestion?

Please contact our Service Desk


This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. https://creativecommons.org/licenses/by-sa/4.0/