Re: Feedback request | Documentation site reorg, switch to Markdown

[Matthew Paul Thomas]

Peter Matulis wrote on 23/02/17 00:03:
> 
> On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas …
>> 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.
> 
> The idea is to improve upon what we have, not to achieve perfection.

For sure. Imperfection is not my claim. My claim is that it would be
worse than what we have.

>…
> You've outlined some solutions in the GH issue, some of which are easy
> to implement and some of which are significantly harder. I don't see
> anything insurmountable however. We have a web team looking at this
> and they happen to be very good at what they do.

I know they’re good. I work right next to them. This month I’ve been
working with them. But no matter how good a team is, some things are
much harder than others, some things are naturally prioritized ahead of
others, and some things never get done. You can’t help but remind me of
the bureaucrat who reassures Indiana Jones that “Top Men” are working on
the soon-to-be-forgotten Ark of the Covenant.

As a demonstration, see <https://insights.ubuntu.com/>. Despite the best
of intentions, after four and a half years, the Web team still have not
quite managed to make it consistent with <https://www.ubuntu.com/>. It’s
similar enough that you can tell the differences are accidental, rather
than deliberate: a different logo rendering, a differently styled search
field returning unhelpfully different results (how am I supposed to know
whether the info I want is an “insight” or not?), even an
unintentionally different shade of orange.

That case was more excusable because it was a new site, with a dynamic
CMS, for new materials. Moving existing, static materials to a separate
site is what is so egregious here.

> Your first option (your preferred I'm presuming) is to simply
> integrate docs into a project's website (a traditional design). This
> has downsides too: every doc project would have its own branding,
> losing the advantage of a consistent "doc theme" that users will most
> likely prefer as they jump from Juju to MAAS to Landscape,
> technologies that are often used in tandem.

So we disagree about what’s more important: consistency between
documentation of different products, vs. consistency of a product’s
documentation with the rest of the product’s pages.

I think consistency between documentation of different products is less
important, because the number of interactive elements is tiny. It’s not
as if you’ll click on the wrong button because the buttons are placed
differently in Maas docs than in Landscape docs, or that you’ll fail to
recognize a checkbox because it’s styled differently in the Juju docs
than the Ubuntu Core docs. They contain nary a button or checkbox in the
first place! If we were talking about signup forms, or checkouts, or
video players, that would be a better argument.

And I think consistency between documentation and the rest of the pages
about a product is more important, because (as I said before) while some
things may be definitely “documentation” and some definitely not, other
pages will live in a fuzzy area between the two. Having “Docs” as a
category is a common mistake, but still a mistake — like when a company
categorizes its wares into “Products” and “Solutions”, because they know
which is which, and they haven’t realized that nobody else does.

Even if I’m wrong about all that — even if “Docs” are a clear and
definite thing, and there are people who really really want their Juju
and Ubuntu Core and Maas documents to have a consistent theme — they
could just use readthedocs.org, which would do a far better job than
docs.ubuntu.com simply because it *also* documents thousands of other,
non-Ubuntu-specific projects a developer might be jumping between.

> We can always tweak each project's subpage (e.g.
> docs.ubuntu.com/maas <http://docs.ubuntu.com/maas>) so that it retains
> some "loyalty" to the parent site

Re: 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.
 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
 vs.  (great!)
with  vs.  (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”
 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

-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam