Project documentation

There are different ways documentation can be written and published within FINOS.

1. GitHub and Markdown, probably the simplest and most intuitive approach: every file written in MarkDown format and hosted in GitHub is automatically parsed and visualised by GitHub; the README.md file located at the root of a project directory is parsed in the GitHub project homepage, which is now a well established best practice to guide consumers to get started with a project. Read more on GitHub Readme doc page
2. GitHub Wiki is a service that is available for every GitHub repository; it can be enabled/disabled via the GitHub repository settings and provides a dedicated Git endpoint that can host Markdown files and generates its web version.
3. GitHub Pages, to customise the look 'n feel of the page and publish the HTML version of your project docs in a custom domain name (ie myproject.com), yet keeping Markdown as documentation language and GitHub as hosting system; GitHub Pages basically reads HTML and Markdown files from a specific repository folder or branch (configured via GitHub repo settings) onto an HTTP endpoint; finos.github.io is a basic example of GitHub Pages, which uses plain HTML (and Javascript) to build the website, but alternative interpreters can be plugged into GitHub Pages, such as:
   1. Docusaurus is the most complete and recommended tool to easily manage project documentation on GitHub; is allows to manage content in MarkDown files, configure navigation and sidebars, manage versioning and is highly customizable using React.
   2. Hugo, an alternative to Docusaurus that generates static HTML using Go Templates and some predefined conventions
   3. Jekyll, a Ruby-based static site generator that is embedded in GitHub Pages; it is highly customisable using variables, custom layouts, HTML blocks
4. Atlassian Confluence can be used for any FINOS Program activity; each program has a dedicated Confluence Space (see the full list), where sub-pages can be created to host activity-specific documentation.