coapp-developers team mailing list archive

[Garrett Serack <garretts@xxxxxxxxxxxxx>]

Well, since I'm going to spend the next week or so writing docs, I'll start by chiming in.

The wiki's not a bad place to start (GitHub's wiki is Markdown, so that's a good thing).

But I think since it's so easy to write Markdown, (and we can add images, etc) we should just start creating pages in the coapp.org github project, so that the stuff that's being written is first available for the web, right on the CoApp site.

Now, that brings up an interesting issue. CoApp's static site is generated using a markdown-powered engine called Jekyll. That's written in Ruby (with the syntax-highlighter (Pygments) written in Python).  Setting up Ruby, Python, Jeykll and Pygments on Windows is a real hassle. If only there was a tool to help install stuff, eh?

So, I've been looking at alternatives to jekyll, that are easier to setup (so others can git clone, and add pages easily).

I think I've found what I'm looking for: there is a node.js app called 'DocPad' that does what Jekyll does, but it's a hell of a lot simpler to setup, plus writing extensions in coffee-script or javascript is a lot easier than Jekyll's Ruby.  

I'm just writing a plugin that uses a Pygments webservice to do the syntax highlighter-which wasn't all that hard.

I'm pretty sure it won't take too much work to move the existing site over to using DocPad, at which point, it should be open season on writing docs.

G
________________________________________
From: coapp-developers-bounces+garretts=microsoft.com@xxxxxxxxxxxxxxxxxxx [coapp-developers-bounces+garretts=microsoft.com@xxxxxxxxxxxxxxxxxxx] on behalf of Mateusz Łoskot [mateusz@xxxxxxxxxx]
Sent: Thursday, December 15, 2011 4:22 PM
To: coapp-developers@xxxxxxxxxxxxxxxxxxx
Subject: [Coapp-developers] Awesome documentation for CoApp

Folks,

This is my first post here, so Hello All!
The documentation seems to be in early stage of development.
AFAIS, the idea is to have it developed and hosted as GitHub Wiki pages.
Is that so?
Is the Wiki for documentation really a good idea?

I think there could be a better approach and results [1] achieved,
very simple in form, reach in content, beautifully presented, minimal,
based on human-friendly input format (Markdown, reStructuredText, etc.),
with multiple output formats possible (e.g. Sphinx is a good example).

[1] Slides 28-74 http://warpspire.com/talks/documentation/

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net

_______________________________________________
Mailing list: https://launchpad.net/~coapp-developers
Post to     : coapp-developers@xxxxxxxxxxxxxxxxxxx
Unsubscribe : https://launchpad.net/~coapp-developers
More help   : https://help.launchpad.net/ListHelp