Feedback request | Documentation site reorg, switch to Markdown

[Stephen M. Webb]

On 2017-02-22 08:21 PM, Peter Matulis wrote:
> On Thu, Feb 16, 2017 at 8:25 AM, Stephen M. Webb <stephen.webb at canonical.com <mailto: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?

No, they're great. Someone spent a lot of time larking some text a bold and some text as teletype.  Markdown is a
wonderful way of writing HTML documents in formalized plaintext.

The problem is that "documentation" is an umbrella term, referring to online web content like marketing-oriented
overviews, tutorials, technical reference manuals, developer guides, and so forth.  It also refers to the printable
manuals that many organizations require with their server installations, and to the help system that desktop users rely
on on their disconnected machines.  Talking about "the documentation" is bound to cause problems because it's not just
one thing that one team is interested in.

Different types of documents require different levels of input, different toolchains, and different workflows.  What is
good for an overview web page for a single project is not what's good for a detailed procedural manual for maintaining a
server.

The initial suggestion on this thread seems along the lines of "lets toss out all our user documents and replace them a
small subset of simple web pages."  I think this is a poor idea, since the Ubuntu documentation is already poor enough
that I myself usually rely on Arch and Fedora documentation for what I need.  I find that a continuing embarrassment.

> 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.

Why not start with a list of existing documents, the intended audience, the expected contributors, and the required
toolchain.  We could then extend that list with those you may net be aware of, and then evaluate each to see if we still
want to maintain the document, whether we want to migrate to different technology (discussing the pros and cons of
each), and how we want to see it published.

To me, that would lead to a more focused discussion.  I would hope the result is a clearly stated Ubuntu policy, plus
maybe some easy-to-install metapackages that deliver the required toolchains and stylesheets to help get authors up and
running for anything more complicated than entering some markdown in a browser text field.

-- 
Stephen M. Webb  <stephen.webb at canonical.com>