⚠️ IMPORTANT: Please fill out this template to give us as much information as possible to consider/implement this update.
Summary
Per @tesla809, we should add a Github pages website for documentation.
Motivation
This could create a clean and easier to read source for documentation, and since it is built directly off markdown in the github repo, would not require a lot of extra effort once configured.
I could see this working out a few ways:
-
Create a separate repo, name has to match org name: COVID-19-electronic-health-system.github.io, contains all the documentation for the organization.
-
Create a gh-pages branch in the .github repo, that contains all the documentation for the organization.
-
Create a gh-pages branch in the Corona-tracker repo, that contains all the documentation for Corona-tracker, and follow the same format for each repo.
There are options to attach this to one of our domains as well, such as docs.coronatracker.me.
It really depends on if we want the documentation to be centered on the organization or centered on the product, and each option can expand as the orgnization/project(s) grow.
Possible Alternatives
Leave as-is, which includes documentation presented in markdown files, typically the README.md file of a folder. The current documentation flows: Org Level --> Repo Level --> Folder Level and should contain back-links to the top.
Additional Context
The first goal of the documentation is to be easily accessible and easy to navigate within Github itself. This would translate well to a website.
The flow of information should be considered whenever creating documentation, emphasizing links to canonical references when possible, and at least linking back one level in the folder structure like a bread crumb.
Summary
Per @tesla809, we should add a Github pages website for documentation.
Motivation
This could create a clean and easier to read source for documentation, and since it is built directly off markdown in the github repo, would not require a lot of extra effort once configured.
I could see this working out a few ways:
Create a separate repo, name has to match org name:
COVID-19-electronic-health-system.github.io, contains all the documentation for the organization.Create a
gh-pagesbranch in the .github repo, that contains all the documentation for the organization.Create a
gh-pagesbranch in the Corona-tracker repo, that contains all the documentation for Corona-tracker, and follow the same format for each repo.There are options to attach this to one of our domains as well, such as
docs.coronatracker.me.It really depends on if we want the documentation to be centered on the organization or centered on the product, and each option can expand as the orgnization/project(s) grow.
Possible Alternatives
Leave as-is, which includes documentation presented in markdown files, typically the README.md file of a folder. The current documentation flows:
Org Level --> Repo Level --> Folder Leveland should contain back-links to the top.Additional Context
The first goal of the documentation is to be easily accessible and easy to navigate within Github itself. This would translate well to a website.
The flow of information should be considered whenever creating documentation, emphasizing links to canonical references when possible, and at least linking back one level in the folder structure like a bread crumb.