Infusion-docs with DocPad

[Bates, Simon]

Hi all,

Apologies for the delay in following up on the documentation conversation. I was away from work for a couple of weeks.

This week, I have been working on some GitHub and DocPad interoperability to enable us to view the documentation in both the GitHub source view and rendered with DocPad. I've updated my https://github.com/simonbates/infusion-docs-docpad with the following:

- Pages are now call Page.md rather than Page.html.md
- I have in place regular expression replacement of links (some details below) so that we can use link targets of Page.md in our markdown pages -- when viewed on GitHub, these links will work, and when rendered with DocPad, the links will be replaced with Page.html

My thinking here is that there is some value in being able to view the documentation, follow links, and edit through the GitHub UI as well as locally with DocPad. Now, I can imagine that we might adopt functionality in the future that is DocPad (or other documentation/site generator) specific because it offers us something that GitHub cannot do -- and that functionality would not render consistently across GitHub and our final generated docs. But, I think that that can evolve with time and that if our base situation is that the docs are viewable both on GitHub and with the generator, we are in a good place to start.

You can view my DocPad version of the docs here: https://github.com/simonbates/infusion-docs-docpad/blob/master/src/documents/index.md

I'd like to propose the following path forward:

1. We continue our conversion process as we have been doing so far, adding docs to https://github.com/fluid-project/infusion-docs
2. In parallel, I will maintain the DocPad version of the docs at https://github.com/simonbates/infusion-docs-docpad which we will use for testing
3. We go ahead and start on some design and templating/styling for the docs
4. Once we are happy with the DocPad version of the docs, we update the main infusion-docs repo

Please let me know if you have thoughts.

As mentioned above, here are some notes on the link replacement. I'm using this regular expression for link replacement: content.replace(/(<a\s[^>]*href="[\w]+)\.md(["#])/gm, '$1.html$2') Please have a look at it and see if you can see any issues. I'm aiming to be conservative to start and the expression will very likely need expanded in the future (for example it won't handle links with "/" or ".." currently) but I'd like to do that as needed.

Thanks,
Simon

-----Original Message-----
From: Colin Clark [mailto:colinbdclark at gmail.com] 
Sent: Friday, May 30, 2014 4:39 PM
To: Tony Atkins
Cc: Bates, Simon; fluid-work at fluidproject.org
Subject: Re: Infusion-docs with DocPad

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