Documenting magasin
0.1 Documentation policy
Magasin is based on a handful of underlying technologies such as docker, kubernetes, helm and comprises several components which are mature and complex products by themselves; not to mention that all these technologies and components generally have very comprehensive documentation.
For that reason, instead of reinventing the wheel by duplicating all the existing documentation - the goal of magasin’s documentation is to provide practical and task-oriented tutorials or step by step guidance in the context of magasin.
The documentation should cover the needs of the following users in mind:
Non-technical End Users (business users) - These are users who may be tech-savvy and are able to describe or design an application’s intended functionality, but do not participate in writing the code that constitutes an application. They are mostly interested in the visualization part, how to use the business intelligence dashboards, and the potential use cases of magasin applied to their business.
As a subset of these users, we can consider the business analysts who may be evaluating the solution.
Technical End Users - These are users with a technical background such as data analysts, data engineers and data scientists. They work mostly on the building data ingestion pipelines, running analyses and writing reports, and creating predictions models among other tasks.
System Administrators (operations) - They are the responsible of setting up and maintaining an instance of magasin. They are concerned about permissions, security, reliability, monitoring…
Developers and contributors - They are technical people that need to understand how magasin works internally in order to enhance the product itself.
0.2 Documentation of our own utilities
In order to enhance the user experience within magasin, we are developing custom a set of utilities, scripts and applications; that serve as a glue between components or that act as accelerators of common operations (such as backing up, upgrading etc)
It is a essential to document the source code including examples of usage for other future developers and contributors benefit.
Depending on the use case for a given tool, there must be sysadmin and/or user documentation that explains how to use these utilities.
For those utilities and scripts that automate common processes (for example backing up the database of a component), corresponding documentation on the manual process will be provided. This is because each magasin component may be setup in multiple ways hence by providing the manual steps the user will have more control in case the assumed setup by the utility is not compatible with their environment.
1 Magasin website and documentation
Magasin website (http://unicef.github.io/magasin) uses quarto as the open source technical publishing system. It allows us to focus on writing markdown and it generates a static website.
Quarto is well integrated with Visual Studio Code, and has a preview feature.
1.1 Website release
The website is published in the Github Page. The resulting site is in the gh-pages branch of the main repository. The URL http://unicef.github.com/magasin.
1.1.1 ** NEVER USE quarto publish gh-pages **
Whereas quarto command line has the option of releasing to github pages through the command line you shall NEVER use it.
This command wipes out all the gh-pages contents and then puts a fresh version of the site. This is because magasin’s gh-page contains some additional files such as the helm repo index (index.yaml) and the installer scripts (install-magasin.sh) which are not managed by quarto publication.
The right way to release the website is to use publish-web GitHub Action whose source code is in the file .github/workflows/publish-web.yml within the main repo.