Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

On Thu, Feb 23, 2017 at 3:03 PM, Matthew Paul Thomas <mpt at canonical.com>
wrote:

> Peter Matulis wrote on 23/02/17 00:03:
> >
> > 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.


>
I'm sure the web team will consider your concerns. I'd like to start out
with an optimistic note however. Also, there's a lot of subjectivity at
play 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.
>
>
Lower down I proposed a compromise.


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


>
I think people spend a lot of time reading (and revisiting) documentation.


> 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.
>
>
IMO, there's nothing wrong with a link that points to documentation.


>
> 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.
>
>
That's a new idea.


>
> > 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).
>
>
I'm not sure which technologies will come next.


>
> > 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.
>
>
I've been told it's possible.


> >> (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.
>
>
Thanks. You've just provided ammunition to help me get rid of those
documents. I don't like them.


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


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


> 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?”
>
>
I was merely providing context to my assertion. That it wasn't only my
belief but the belief of others as well.


> 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.
>
>
As far as docs.ubuntu.com goes, I'd like to include only content that is
supported by peer-review and curation mechanisms. People could continue to
access the wiki on help.ubuntu.com.


> > 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?
>
>
I don't think we should get rid of the wiki. It has value for many people.

- People like a place to write stuff.
- Some people like to take their chances even if a page hasn't been updated
in a long time or they couldn't find the topic elsewhere.

There are indeed some good things to be found there.

Peter
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-users/attachments/20170224/d1b98046/attachment.html>