Infusion-docs with DocPad

[Tony Atkins]

Hi, Simon:

+1 for using a static site generator as long as the docs themselves are
stored as markdown.  To explain a bit:

By chance I ended up using Github Flavored Markdown for recent API
documentation work (I had thought to use apiary, which is basically GFM
plus extra bits).  Based on the experience of putting that in front of
reviewers, the main value I see of your proposed approach is that we can
simply send links to the work in progress on Github to anyone.  Reviewers
don't need to go through the effort of checking out the code or running a
site generator if they're just going through the proposed changes in a
meeting.  As long as we use relative URLs and a single hierarchy for docs,
any links should work in either GitHub or the finished site.

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.

Cheers,


Tony


On Mon, May 26, 2014 at 10:10 PM, Bates, Simon <sbates at ocadu.ca> wrote:

> Hi all,
>
> We have been working on converting the Fluid Infusion documentation to
> Markdown and moving it to GitHub:
>
> https://github.com/fluid-project/infusion-docs
>
> While our initial target for the documentation has been the GitHub source
> browser, our long term plan is to move to a static site generator so that
> we have control over the presentation of the documentation.
>
> Last week I spent a bit of time exploring GitHub pages as an alternative
> to viewing the rendered Markdown in the GitHub browser. My investigation
> left me feeling like GitHub pages was not a great option. Using GitHub
> pages would give us a GitHub manged instance of the Jekyll site generator
> but no templates or styling -- we would have to implement those ourselves.
> This got me thinking -- if we would have to put in the work to template and
> style ourselves to get benefit from GitHub's Jekyll, how much work would it
> be to go ahead and implement a solution that is closer to our long term
> plan?
>
> So, I decided to have a go at moving the documentation that we have
> converted so far to DocPad, a JavaScript static site generator built on
> Node.js. I am using Foundation for the layout and Highlight.js for syntax
> highlighting (minimal styling has been done beyond the defaults). The
> result is in GitHub and I have included instructions in the README.md on
> how to run DocPad locally so that you can try it out:
>
> https://github.com/simonbates/infusion-docs-docpad
>
> I would like to propose that we go ahead and move to DocPad and I would
> like to get input on what others think of this option?
>
> Here are some observations and thoughts:
>
> * the documentation is in src/documents (DocPad default but configurable)
> * unprocessed files (CSS, JS, images) are in src/files (DocPad default but
> configurable)
> * I am imagining that we would set up a nightly build to run DocPad and
> upload the generated HTML to a web server (either one we manage, or it
> could be GitHub pages)
> * before we make the pages public, we would need to do some templating and
> styling work
> * DocPad uses file name extensions to specify what processing should be
> done on each file and this results in the documents having names such as
> IoCSS.html.md (meaning convert from Markdown to HTML); this could be a
> little clunky and it is possible to rely on some defaults handling and name
> the documents without the ".html", such as IoCSS.md
> * when serving the pages from GitHub, we link to the Markdown file, such
> as IoCSS.md; switching to DocPad would require us to change our link
> targets to the generated HTML file names, such as IoCSS.html (I am
> investigating this now to see if there is any special link handling that
> might be useful here)
>
> Please have a look at the DocPad version of the docs and let me know what
> your thoughts are.
>
> Thanks,
> Simon
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20140529/ddaac7a5/attachment.htm>