Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

On Thu, Feb 16, 2017 at 8:25 AM, Stephen M. Webb <stephen.webb at canonical.com
> wrote:

Switching from a semantic documentation markup to a non-semantic
> unstructured set of HTML macros that has wretched
> support for anything other than web pages is a net negative gain. Markdown
> was written by coders for coders so they can
> appear to have something like online documentation.  It's the wrong choice
> for something like a manual, API docs, or
> pretty much anything more than marketing quips or blog comments.
>

Here are two sites I know that use Markdown for technical documentation:

https://jujucharms.com/docs
https://docs.ubuntu.com/maas

Is there something wrong with them?

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.

I'm all for a consistent presentation style across Canonical-supported
> media and across all Ubuntu media.  I don't think
> ex-cathedra forcing a workflow and markup switch onto actual writers is
> the right way to achieve that if you're trying
> to encourage participation and quality of content.
>

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.

Peter
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-users/attachments/20170222/8e19d7a1/attachment.html>