Re-usable, flexible documentation "platform" for projects

[Jonathan Hung]

Hi everyone,

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.

Relevant links:

   - 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.

- Jon.

-- 

*JONATHAN HUNG*

INCLUSIVE DESIGNER, IDRC



*T:* 416 977 6000 x3951

*F:* 416 977 9844

*E:* jhung at ocadu.ca



*OCAD UNIVERSITY*

Inclusive Design Research Centre

205 Richmond Street W, Toronto, ON, M5V 1V3



www.ocadu.ca

www.idrc.ocad.ca
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20151007/3577bcd4/attachment.html>