On Fri, Mar 21, 2014 at 1:47 PM, Marco Ceppi <marco.ce...@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 > > This is pretty biased towards markdown, generally restructured text has a tradition and success for being used for documentation.. Any plain text format is big win imo from what we have today. http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext So the question becomes, what format would be preferential among developers for writing docs . The candidates so far are as follows 1. Markdown 2. Restructured Text 3. HTML5/CSS preprocessors/custom scripts (Currently in use)
-- Juju-dev mailing list Juju-dev@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
