docs-platform restructuring

Antranig Basman antranig.basman at colorado.edu
Wed May 11 17:19:47 UTC 2016


Hi Jon - yes, this is really important work - since we are rapidly gaining new repos that need to take 
advantage of a docs platform. The refactoring certainly needs to be done so that our rendering and 
publishing workflow can be reused.

I'm not sure about item 1, with respect to decoupling ourselves from the renderer. As far as I'm aware, our 
particular structure (with site-structure.json, etc.) is one that is particularly parsed by the docpad 
platform. Are you aware of other platforms which might viably be substituted for it?

I'm not quite sure I follow the diagrams in the Google Drawing - it would help to have an annotation as to 
what the black arrows mean.

It says "subdirectory nesting determines the navigation" - is it possible to make this work without all the 
other metadata in site-structure.json?

It's unclear what happens to all the content we currently have in "static" - does it all just get stuck into 
subdirectories of "site-renderer"? What will be the contents and structure of the "config.json" file which 
you have in each of these directories?

This looks like quite an ambitious plan (especially the idea to become docpad-agnostic) and it might be nice 
to have an intermediate factoring point that just captures our existing workflow and puts it into a reusable 
module in npm rather than our current github clone scheme.

Cheers,

Antranig

On 09/05/2016 18:07, Hung, Jonathan wrote:
> 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
>
>
>
> _______________________________________________________
> fluid-work mailing list - fluid-work at lists.idrc.ocad.ca
> To unsubscribe, change settings or access archives,
> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
>



More information about the fluid-work mailing list