I WANT YOU, to give me your feedback (Juju docs!)

[Marco Ceppi]

Hi everyone,

I'm spreading this email out across the juju-core, juju, and juju-gui list
to start a discussion about the next format for the docs. Currently, I've
worked on a proof of concept to converting the docs to Markdown and it's
going really well. Using python-markdown with a few custom plugins to
handle the unique user friendly features the docs provide.

However, I wanted to get feedback on the choice of formatting. Markdown has
quickly become the choice of formatting for new projects, it's used heavily
on the StackExchange network as well as Github. It's even a recommendation
for the charm README files and charm-tools creates a Markdown template for
use. Finally, it bares similarities to RST but tends to be more forgiving
and require less syntax to use.

To quote the John Gruber, Markdown creator:

> While Markdown's syntax has been influenced by several existing
text-to-HTML filters, the single biggest source of inspiration for
Markdown's syntax is the format of plain text email.

This low barrier of entry is likely one of the reasons it's grown in
popularity over the years.

I'm curious of people's opinions, do you support this move to Markdown? Do
you have other formats for docs in mind and if so reasons that style
instead? After some time I'll consider the responses, for and against, as a
poll for which language to move the docs to as I finish my conversion

Thanks,
Marco Ceppi
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20140321/2ea6fee8/attachment.html>