docs-platform restructuring

Hung, Jonathan jhung at ocadu.ca
Mon May 9 17:07:54 UTC 2016


Hi everyone,

I will be taking on the task of setting up a hosting strategy for the Inclusive Design Guidelines, and the docs platform is likely what we will use because it’ll get us what we need very quickly.

However, there’s a long standing issue with the docs platform - it isn’t structured in a way that is easy to maintain. The biggest problem is that any site wishing to use the “docs-platform” needs to start from a clone of the “docs-template” repository. This creates a tricky problem when updates are made to docs-template - there would be merge conflicts with each derivative docs site, and all merges will need to be done by hand.

One way to resolve this issue is to refactor and restructure the existing docs platform by:

1. Decouple the content from the renderer (i.e. docpad) platform - this makes content easier to maintain and more easily repurposed.

2. Refactor docs template into more easily maintainable parts - for example customizable template parts should be refactored into template partials.

3. Set up a tool that will just handle rendering of the content into a static website. This means we will only have to maintain a single docpad renderer instead of multiple clones as it is right now. (We would also be able to add other renderers for formats such as PDF and EPUB3).

An example of what this might look like can be found in this Google Drawing<https://docs.google.com/drawings/d/1de4ZzazgSC-81TZPhr-x_INGh9Q91WpLeJ1aLStfipo/edit?usp=sharing>.

As part of the work to create a hosted version of the Inclusive Design Guidelines, I would like to do this restructuring and refactoring work as well. If it works well, I would then come back to the community and propose to migrate other documentation sites (like the Inclusive Learning Design Handbook, First Discovery Tool docs, and the Infusion docs) to this organization.

This should only affect how the is structured and maintained.

Please share your thoughts.

- Jon.

--

JONATHAN HUNG, Inclusive Designer

Email: jhung at ocadu.ca<mailto:jhung at ocadu.ca>

OCAD UNIVERSITY

Inclusive Design Research Centre
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20160509/024529c8/attachment.html>


More information about the fluid-work mailing list