Thanks for the info Simon. +1 for the proposal. I have also left a comment inline below.
Thanks Justin On Jun 18, 2014, at 11:22 AM, Bates, Simon <[email protected]> wrote: > 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. This could be an issue now that we have our tutorials contained within folders. https://github.com/fluid-project/infusion-docs/tree/master/tutorial-gettingStartedWithInfusion > > Thanks, > Simon > > -----Original Message----- > From: Colin Clark [mailto:[email protected]] > Sent: Friday, May 30, 2014 4:39 PM > To: Tony Atkins > Cc: Bates, Simon; [email protected] > Subject: Re: Infusion-docs with DocPad > > Hi Tony, > > On May 29, 2014, at 6:56 AM, Tony Atkins <[email protected]> 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 > _______________________________________________________ > fluid-work mailing list - [email protected] > To unsubscribe, change settings or access archives, > see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work _______________________________________________________ fluid-work mailing list - [email protected] To unsubscribe, change settings or access archives, see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
