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

[Nick Veitch]

I feel there needs to be a slight (big) addendum to this:

1. There is no specific timetable for this, so people shouldn't be
expecting big changes next week or something.

2. It isn't a question of Markdown or stay as it is. If you have
strong feelings about RsT or SGML or Mallard or who knows what, I'd
like to hear about them too. If there are specific reasons for using a
particular format, please mention them. Bear in mind that the primary
goal is to give USERS the documentation they want/need.

3. Ideally I would like to move to a position where we could use one
source format and set of tools for all docs projects in CDO, but that
is a longer term goal.

4. This isn't a democracy. I would be interested to hear what formats
people are comfortable with, but if 10 people who have never
contributed to the docs before all say DocBook or something, that will
have to be slightly balanced by whether we can make an acceptable
workflow around that for the people who actually do the majority of
the work (i.e. me) and others who make more frequent contributions.

The bottom line is, I would like the docs to be easier to contribute
to. There are too many features landing that aren't documented and
this really needs to change, for everyone's benefit.

Nick

On Fri, Mar 21, 2014 at 6:45 PM, Curtis Hovey-Canonical
<curtis at canonical.com> wrote:
> On Fri, Mar 21, 2014 at 1:47 PM, Marco Ceppi <marco.ceppi at canonical.com> wrote:
>> 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
>
> +1
>
> Caveat that I think we need a post proc to format input examples and
> output examples and possibly glossary links.
>
> Given that 1.18.0 can be out next week. 1.18.0's docs will be written
> in the current HTML format so that we can deliver them next week
> too...unless you happen to already have tip and unstable docs already
> converted to markdown and a post processor ready to go.
>
>
> --
> Curtis Hovey
> Canonical Cloud Development and Operations
> http://launchpad.net/~sinzui
>
> --
> Juju mailing list
> Juju at lists.ubuntu.com
> Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju