<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Thu, Feb 16, 2017 at 8:25 AM, Stephen M. Webb <span dir="ltr"><<a href="mailto:stephen.webb@canonical.com" target="_blank">stephen.webb@canonical.com</a>></span> wrote:</div><div class="gmail_quote"><br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Switching from a semantic documentation markup to a non-semantic unstructured set of HTML macros that has wretched<br>
support for anything other than web pages is a net negative gain. Markdown was written by coders for coders so they can<br>
appear to have something like online documentation.  It's the wrong choice for something like a manual, API docs, or<br>
pretty much anything more than marketing quips or blog comments.<br></blockquote><div><br></div><div>Here are two sites I know that use Markdown for technical documentation:</div><div><br></div><div><a href="https://jujucharms.com/docs" target="_blank">https://jujucharms.com/docs</a><br></div><div><a href="https://docs.ubuntu.com/maas" target="_blank">https://docs.ubuntu.com/maas</a><br></div><div><br></div><div>Is there something wrong with them?</div><div><br></div><div>There is more, however, to consider than visual results. A choice of format impacts source text readability and ease of use. I am intimately familiar with both the Ubuntu Server Guide as well as both the above projects and I can tell you that at least Juju documentation has more non-Canonical contributors than the Server Guide. This is an important fact, especially when you consider that Juju is a tiny niche project.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I'm all for a consistent presentation style across Canonical-supported media and across all Ubuntu media.  I don't think<br>
ex-cathedra forcing a workflow and markup switch onto actual writers is the right way to achieve that if you're trying<br>
to encourage participation and quality of content.<br></blockquote><div><br></div><div>I don't see any "ex-cathedra forcing" and "markup switch" going on. This email thread, with the word "feedback request" in its subject and "proposal" in its second sentence, was sent as far and wide as it possibly could. There is a lot of discussing going on too.</div><div><br></div><div>Peter </div></div></div></div>