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 <mpt at canonical.com
>…
>> 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 (e.g. maas.io <http://maas.io>) all
> the while maintaining the foundation of a central theme. I believe I
> just described your second option.
> 
> In terms of search, your first option gains the ability to scan the
> rest of the project's non-docs but you also lose the ability to search
> across multiple doc projects which is something we're planning. For
> the aforementioned technologies, and soon others, this is a much more
> powerful feature IMO.

If “soon others” includes Snapcraft, you’ll need to combine search
results from multiple sites anyway (because Snapcraft docs will stay off
docs.ubuntu.com).

>> 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.
> 
> If we need to write something in HTML in the Markdown files then we
> can do so. The parser handles this fine. Fake News!!

The copyable command lines involve an external JavaScript file, so it
wouldn’t be just a matter of inserting HTML — unless you expected and
allowed inlining of scripts into the HTML.

>> (There are minor problems too, mainly involving the ways that
>> browsers and search engines would treat docs.ubuntu.com
>> <http://docs.ubuntu.com> as a separate Web site.)
> 
> Please elaborate. I'm not a web guy.

One example is that if you search Google for “Maas”, the relevant search
result includes direct links to the “Get started”, “Tour”, and “How it
works” sections — but not to the “Docs” section, because it is (as far
as Google can tell) on a different site.

A second example is that for any product, if you set your browser’s zoom
level on its docs.ubuntu.com pages, it won’t carry over to the rest of
the site, or vice versa.

A third example is that any UI that arranges pages by site — like
Safari’s tab switcher, or most browsers’ history windows — will assume
that a product’s docs.ubuntu.com pages are a separate site.

As I said, minor problems, but symptoms of the weird IA involved.

>> 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.
> 
> There was some history bundled into my statement. It was agreed at a
> community doc meeting a while ago (2014?) that we would no longer
> consider the Ubuntu help wiki to be documentation. The reasoning was
> that documentation is more than text published on a web site. It has
> to meet certain criteria, like being subject to peer reviews and
> having a reasonable degree of maintenance applied (the official
> documentation has this). One concrete action resulting from this
> decision was to replace the header of "Community Documentation" on
> help.ubuntu.com with "Community Help Wiki".

“Who are you gonna believe, the minutes of a Community Documentation
Team meeting from 2014, or your lying eyes?”

If we’re going to cast into history, I’ll go back further: to July 2006,
when I included “documentation” on a list of words to avoid in anything
produced or overseen by the Documentation Team.
<https://lists.ubuntu.com/archives/ubuntu-doc/2006-July/006669.html>

The reason was that even if software developers see that word as a
meaningful descriptor, end users do not. I can confidently predict that
for end-user help, declaring that some pages are “documentation” — or
even “official documentation” — and that others are not, will not have
altered user behavior one iota.

> It's better that a set of search results points to either reliable
> information or unreliable information, not a mix of the two. So it
> actually makes sense to separate them, in terms of searching.
>…

If it’s really “unreliable”, why host it at all?

-- 
mpt