In this technical part of the workshop you:
- Set up your local environment to build a documentation portal
- Understand and configure your own distributed source publishing flow
- Write simple markdown document with additional metadata
- Publish the portal to GitHub Pages
The following technologies are used:
- Git and GitHub and GitHub Pages
- DocPad and documentation portal template based on it: docpad-skeleton-apidoc
- Chewie, distributed source publishing tool
Source control management system for any kind of text files. Allows to keep many versions of one file and merge those into one at any time. Set of files can be grouped in so called repositories.
Most known tools:
- Git CLI
- GitHub Desktop
- SourceTree
Git hosting service + much more like:
- Projects management
- Issues reporting
- Wiki
Most known alternative: Bitbucket
Free static pages hosting service. Sample lib that hosts its documentation page using GitHub Pages: http://getbootstrap.com/
Most known alternative: I don't know anything better
Static site generator + much more. By defining layouts you can generate whole documentation portals with sources written in simple markdown syntax.
Most known alternatives:
- Jekyll and template from Tom Johnson,
- Sphinx that is probably behind the Write the Docs community.
Simple markup language used in plain text files. Later such file can be converten into any other format like HTML for example. Sample usage: this document and basically all other documents that describe this workshop.
Most known alternatives:
Chewie makes it possible to have documentation content distributend in different locations. It supports content registry management, independent docu generation and publishing.