Re: I WANT YOU, to give me your feedback (Juju docs!)
+1 to Markdown. Nice integration with GitHub (edit, preview, etc.), pretty much a de facto standard on there. I'd also like to see us using GitHub Pages for unstable/unreleased versions of Juju. On Sat, Mar 22, 2014 at 1:47 AM, Marco Ceppi 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@lists.ubuntu.com > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju-dev > > -- Juju-dev mailing list Juju-dev@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
Re: I WANT YOU, to give me your feedback (Juju docs!)
I have contributed to the Juju documentation and the process was harder than the format. Another vote for Markdown from me. If we truly want contributions from the community we should keep the barrier of entry low. It is written somewhere in the docs that people can and should contribute to the Juju documentation. The Juju community already needs to know markdown for the README.md files in the charms, so it makes sense to use the *same* format for the docs. - Matt Bruzek On Fri, Mar 21, 2014 at 12:47 PM, Marco Ceppi 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@lists.ubuntu.com > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju-dev > > -- Juju-dev mailing list Juju-dev@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
Re: [Juju-gui-peeps] I WANT YOU, to give me your feedback (Juju docs!)
On Fri, Mar 21, 2014 at 1:47 PM, Marco Ceppi 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
Re: I WANT YOU, to give me your feedback (Juju docs!)
+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 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@lists.ubuntu.com > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju-dev > > -- Juju-dev mailing list Juju-dev@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
I WANT YOU, to give me your feedback (Juju docs!)
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@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
