Feedback request | Documentation site reorg, switch to Markdown

[Matthew Paul Thomas]

Peter Matulis wrote on 15/02/17 21:58:
>…
> There is a proposal put forward by Canonical to provide a consistent
> look and feel for all Ubuntu documentation, regardless of whether it
> is primarily maintained by the Community or by Canonical. The idea is
> that this will provide a better user experience for the reader. The
> process of building and publishing would also change so that all
> projects will use the same method. Not only will this make it easier
> compared to current methods but it will allow people to work on
> different projects using the same workflow and toolset.

It’s true that this would let people work on different projects using
the same processes. Others have responded about that.

Unfortunately, I do not think it is true that it would be a “better user
experience for the reader”. I think it would be worse.

(I’m speaking as a designer who has contributed to Ubuntu help in the
distant past, and who may work on developer UI and reference materials
in the near future.)

> Currently, the "Canonical docs" consist of MAAS, Juju, Ubuntu Core,
> and Landscape. There is a central doc site under construction,
> docs.ubuntu.com, that would link to all these documentation sites.

There are two main problems with this approach.

First, inconsistency. Moving documents to docs.ubuntu.com makes it
practically impossible to achieve consistent design, because
docs.ubuntu.com has a different look and navigation from the rest of the
site for each project. The most flagrant example is that docs.ubuntu.com
pages currently don’t even *link to* the rest of the site for the
relevant project.
<https://github.com/ubuntudesign/docs.ubuntu.com/issues/37> Even if that
was fixed, great effort would be required to implement the rest of the
navigation, with the same layout, font, etc on
docs.ubuntu.com pages as on the rest of the project’s site. Compare
<https://jujucharms.com/> vs. <https://jujucharms.com/docs/> (great!)
with <https://maas.io/> vs. <http://docs.ubuntu.com/maas/> (woefully
inconsistent). It would also be much harder to implement a reliable
search function across any site including its docs.

Second, scope. While the sites for each of these projects currently have
a “Docs” section (indeed, Landscape has two), there won’t always be a
clear distinction between what counts as as “docs” and what does not. A
simple example is that “Get started with MAAS 2.0”
<https://maas.io/get-started> is a document, in that it would be
perfectly useful if you printed it out. But it is also of primary
importance on the site, and contains minor interactive elements
(copyable command lines). Similarly you could imagine a walkthrough
document that starts by prompting you for the name of your package, then
fills in sample commands including that package name. A single element
that couldn’t be implemented in Markdown would, apparently, result in
the document having to be hosted separately from all the others.

(There are minor problems too, mainly involving the ways that browsers
and search engines would treat docs.ubuntu.com as a separate Web site.)

Finally, this statement —
>…
> the help wiki, which is not documentation.
>…
is bewildering. Of course the help wiki is documentation. It’s an
unfortunate administrative quirk that help.ubuntu.com has two sets of
documents, each covering much of the same topics. But moving one set to
a separate site would make things worse: for example, it would break the
search.

I suggest instead finding a way to get the doc builder to generate pages
that can be inserted into existing project sites, so that they can be
indexed and navigated in the same way as the rest of the site.

Cheers
-- 
mpt