On Thu, Feb 23, 2017 at 3:03 PM, Matthew Paul Thomas <m...@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
-- ubuntu-translators mailing list ubuntu-translators@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators