Infusion documentation plan

Cheetham, Anastasia acheetham at ocadu.ca
Mon Apr 6 14:15:04 EDT 2015


During last week’s community workshop, we discussed our plans for Infusion documentation. Below is a summary of our discussions. (If you were at the meeting, please let me know if I got anything wrong.)

Documentation is written in Markdown; an HTML version is generated using Docpad.

Immediate Priority:
Our immediate focus is getting the HTML version finished up and deployed. Jon is working on converting the table of contents to have three separate sub-sections and updating the site navigation accordingly.

We will deploy the Infusion documentation at http://docs.fluidproject.org/infusion:
- the “master” version of the docs will be at http://docs.fluidproject.org/infusion/lastest
- versioned docs (i.e. tagged to go with versioned code) will be at http://docs.fluidproject.org/infusion/<versionNumber>
- http://docs.fluidproject.org/infusion will redirect to http://docs.fluidproject.org/infusion/latest

In the future, when we have documentation for other non-Infusion projects (such as the Video Player, Metadata tools), we will deploy them at appropriate subfolders (such as http://docs.fluidproject.org/videoPlayer, etc.)

In the short term, we will deploy the docs using gh-pages. Once we have a Jenkins workflow – along with the TLS certificate – we’ll stop using gh-pages.

After deployment:
Once the documentation is actually deployed to a working URL, we will focus on a few clean-up tasks:
- Thorough testing to ensure there are no links with assumptions about root location.
- The Getting Started tutorial needs updating.
- We will need a landing page for http://docs.fluidproject.org/ (for now, it will redirect to http://docs.fluidproject.org/infusion). Since this will be a landing page for all of our documentation, it will not be part of the Infusion docs repository.
- Anything that currently links to the Markdown version of the docs will need to be updated (e.g. link in demo overlays)
- The Infusion page of http://fluidproject.org will need to link to the new docs site

Longer term thoughts:
- Versioned demos should be referencing versioned documentation.
- When we have documentation for other projects (such as the Video Player), we should try to share as much of the documentation infrastructure as possible. For example, the infrastructure parts (CSS, publishing, etc) could go in a shared repository, and the source Markdown files for each project would live in separate repositories.

--
Anastasia Cheetham – acheetham at ocadu.ca<mailto:acheetham at ocadu.ca>
Inclusive Design Research Centre
Inclusive Design Institute
OCAD University

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20150406/0756d7f2/attachment.html>


More information about the fluid-work mailing list