Re-usable, flexible documentation "platform" for projects
aharnum at ocadu.ca
Mon Oct 19 14:13:50 UTC 2015
I built some experimental Docker wrapping around this stack (mostly just a shell script at this point): https://github.com/waharnum/dockpad/blob/master/README.md – this may not be of interest to anyone except me at this point, but it was interesting to explore the possible patterns.
I’d eventually (maybe?) envision a world in which we can use dedicated containers (each one running a web server serving the generated static site) to package and serve sites to the wider world.
I really like static site generators & not just because they make system administration a lot easier compared to a CMS. Good work, John. :)
From: fluid-work <fluid-work-bounces at lists.idrc.ocad.ca<mailto:fluid-work-bounces at lists.idrc.ocad.ca>> on behalf of Jonathan Hung <jhung at ocadu.ca<mailto:jhung at ocadu.ca>>
Date: Wednesday, October 7, 2015 at 8:35 AM
To: Fluid Work <fluid-work at fluidproject.org<mailto:fluid-work at fluidproject.org>>
Subject: Re-usable, flexible documentation "platform" for projects
In the past we've discussed the desire to move away from CMS driven sites for documentation, and towards an open and flexible solution which fits the way we work as a community.
In response to this, I have created a collection of technologies which I hope addresses our needs. The solution is based off of DocPad static website generator, and uses a template skeleton which projects and individuals can customize to fit their particular documentation needs.
* Docs-core: github source<https://github.com/jhung/docs-core>
* Docs-template: github source<https://github.com/jhung/docs-template/tree/jhung-repo-references>, demo<https://jhung.github.io/docs-template/>
Some key features of this documentation "platform":
* responsive out of the box
* Fluid UI Options built-in
* extensible and customizable using Stylus, Handlebars, Markdown, HTML, and CSS
* everything is transparent and done through github (fork it, modify it, fix it, improve it)
* content is malleable (written in markdown) thus can be deployed to different delivery systems (i.e. EPUB3, PDF, etc.).
* no more databases!
Here is an example of the docs platform running in an integrated environment: https://jhung.github.io/docs-inclusive-learning/
Please note: there is a known limitation where the internal links assume content is located off the root URL. Hence many of the internal links in this example will not work deployed thusly, but will work if deployed to a proper domain.
I think this documentation platform (docs-core, and docs-template) would be useful for Fluid Project as documentation and communication is a large part of the project. By contributing this tool to Fluid, other projects would then be able to implement new documentation sites easily.
There are existing issues and feature requests which I have documented in the Fluid Project bug tracker<https://issues.fluidproject.org/issues/?jql=project%20%3D%20FLUID%20AND%20status%20%3D%20Open%20AND%20component%20%3D%20%22Tech.%20Documentation%22>. I hope these issues and features will be addressed over time.
Please take a look and let me know what you think. I'm happy to provide more detail and answer questions.
INCLUSIVE DESIGNER, IDRC
T: 416 977 6000 x3951
F: 416 977 9844
E: jhung at ocadu.ca<mailto:jhung at ocadu.ca>
Inclusive Design Research Centre
205 Richmond Street W, Toronto, ON, M5V 1V3
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the fluid-work