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

[Joshua Strobl]

I support the move to Markdown formatted text. I'd even further support 
the move to something similar to GitHub Flavored Markdown 
(http://github.github.com/github-flavored-markdown/), which I prefer 
since it supports fenced code blocks and syntax highlighting. I feel 
moving the content to Markdown will lower the barrier for contributors, 
as opposed to moving to formatting documentation in something like LaTeX 
(in other words, -1 for LaTeX from me), which is more complex in my opinion.

- Joshua

On 3/21/2014 19:49, Juan Negron wrote:
> Markdown +1 IMO
>
>
> On Fri, Mar 21, 2014 at 10:47 AM, Marco Ceppi 
> <marco.ceppi at canonical.com <mailto:marco.ceppi at canonical.com>> wrote:
>
>     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
>
>     --
>     Juju mailing list
>     Juju at lists.ubuntu.com <mailto:Juju at lists.ubuntu.com>
>     Modify settings or unsubscribe at:
>     https://lists.ubuntu.com/mailman/listinfo/juju
>
>
>
>
> -- 
> Thanks,
>
> Juan L. Negron <juan.negron at canonical.com 
> <mailto:juan.negron at canonical.com>>
> Mobile: +1 408 634 0292
> Cloud Architect
> Canonical Technical Services
> Canonical USA
> GPG : 0A62 BC70 5CBC B4DD F3E6  8A27 A6B1 F3F0 E6B5 F5A3
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju/attachments/20140321/05db0df1/attachment.html>