Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis peter.matulis at canonical.com
Thu Feb 23 00:03:54 UTC 2017


On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas <mpt at canonical.com>
wrote:

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

The idea is to improve upon what we have, not to achieve perfection. As you
know, there are pros and cons to any design.

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.

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


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

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

Please elaborate. I'm not a web guy.


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

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.

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

This is a reiteration of your option #1 which I acknowledged earlier.

Peter
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-translators/attachments/20170222/25195c6f/attachment.html>


More information about the ubuntu-translators mailing list