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

[Nate Finch]

+1

Markdown is great.  It's basically the only way to write HTML that is
actually legible outside of a browser (like in diffs, code reviews, as
you're actually writing it, etc).


On Fri, Mar 21, 2014 at 1:47 PM, Marco Ceppi <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-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20140321/bf4bbaef/attachment.html>