Publishing Strategy
Reference documentation about the adopted strategy for publishing and updating documents on the ALAN Docs website:
JOIN THE DISCUSSION on the strategies presented in this document by visiting Discussions » Policies.
Table of Contents
Since April 2021, the ALAN Docs website has become the official site of reference for any ALAN-related documentation, where Alan users can download the documents in various formats.
Since 2018, the ALAN Docs repository is the official repository for developing and maintaining ALAN-related documentation, in AsciiDoc format. Most of the original documents, previously written in Word or HTML, have already been ported to AsciiDoc.
The website actually stores the document files (mainly in PDF and HTML) built from the AsciiDoc sources found in the repository, or taken from other projects.
This documents describes the strategy and technical aspects of updating the documents on the website, from within the source repository, as well as the policies regarding documents from other sources, linking to external documents, etc.
The ALAN Docs website is hosted through the GitHub Pages service, using the Jekyll CMS (markdown based). The website is reachable via the following URLs:
- https://alan-if.github.io/alan-docs
- https://git.io/alan-docs (posh link alias)
Website contents are served from the published branch of the repository, which is an orphan branch.
This section needs to expand on:
- orphan branches:
- explain how the
publishedorphan branch differs from the other (normal) branches of the repository (or maybe this should go in the repository section?). - add links to orphan branch documentation/articles (non found on Git website and book).
- explain how the
- third party documents:
- what's the policy for documents created elsewhere? (e.g. the StdLib Documentation is build within the StdLib repository, because it needs access to the library sources and examples)
- linking vs hosting — if a third party document is still actively developed, should we host it or just link to it?
- should third party documents be discussed here or in a dedicated section?
- what's the policy for documents created elsewhere? (e.g. the StdLib Documentation is build within the StdLib repository, because it needs access to the library sources and examples)
TBD!
This section needs to cover:
- How publishing from the repository to the
publishedorphan branch works (technical aspects, etc.). - ALAN Manual Beta vs Alpha editions (and branches).