Infusion-docs with DocPad

[Colin Clark]

Hi Tony,

On May 29, 2014, at 6:56 AM, Tony Atkins <tony at raisingthefloor.org> wrote:

> Why is markdown so important?  The main risk in my opinion of using a static site generator is that we could shrink our circle of contributors to just developers, or worse, just developers familiar with our stack.  As long as we keep markdown (or GFM) for the raw document format, we can pretty safely assume that most developers are very familiar with the format.  There are also a range of tools that non-developers can use to edit markdown.  In the "how to work with this" instructions in the README, I would include markdown editor details along side the docpad instructions for devs and site maintainers.

I’m glad you highlighted the issue of ensuring that contributing to our documentation is easy and within reach for non-developers. It’s really question of the right tool for the job. The Infusion framework documentation is written by technical people for an audience of developers, so I think it’s quite reasonable to use a Markdown, Git, and static site generator workflow. It certainly gives us a lot more flexibility in terms of styling, embedding code examples and demos, and a lot more simplicity from the system administrator perspective.

But for other types of resources, we should make sure that the barrier to contribution is very, very low. That’s where a wiki is probably most appropriate. I’m thinking about things like, say, the Inclusive Learning Design Handbook or work documents such as proposals, architecture planning, etc. These should remain in the wiki so that anyone can quickly and smoothly contribute.

Colin