<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas <span dir="ltr"><<a href="mailto:mpt@canonical.com" target="_blank">mpt@canonical.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Peter Matulis wrote on 15/02/17 21:58:<br>
>…<br>
<span class="gmail-">> There is a proposal put forward by Canonical to provide a consistent<br>
> look and feel for all Ubuntu documentation, regardless of whether it<br>
> is primarily maintained by the Community or by Canonical. The idea is<br>
> that this will provide a better user experience for the reader. The<br>
> process of building and publishing would also change so that all<br>
> projects will use the same method. Not only will this make it easier<br>
> compared to current methods but it will allow people to work on<br>
> different projects using the same workflow and toolset.</span><br>
<br>
Unfortunately, I do not think it is true that it would be a “better user<br>
experience for the reader”. I think it would be worse.<br>
<span class="gmail-"><br>
> Currently, the "Canonical docs" consist of MAAS, Juju, Ubuntu Core,<br>
> and Landscape. There is a central doc site under construction,<br>
> <a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a>, that would link to all these documentation sites.<br>
<br>
</span>There are two main problems with this approach.<br>
<br>
First, inconsistency. Moving documents to <a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a> makes it<br>
practically impossible to achieve consistent design, because<br>
<a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a> has a different look and navigation from the rest of the<br>
site for each project. The most flagrant example is that <a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a><br>
pages currently don’t even *link to* the rest of the site for the<br>
relevant project.<br>
<<a href="https://github.com/ubuntudesign/docs.ubuntu.com/issues/37" rel="noreferrer" target="_blank">https://github.com/<wbr>ubuntudesign/docs.ubuntu.com/<wbr>issues/37</a>> Even if that<br>
was fixed, great effort would be required to implement the rest of the<br>
navigation, with the same layout, font, etc on<br>
<a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a> pages as on the rest of the project’s site. Compare<br>
<<a href="https://jujucharms.com/" rel="noreferrer" target="_blank">https://jujucharms.com/</a>> vs. <<a href="https://jujucharms.com/docs/" rel="noreferrer" target="_blank">https://jujucharms.com/docs/</a>> (great!)<br>
with <<a href="https://maas.io/" rel="noreferrer" target="_blank">https://maas.io/</a>> vs. <<a href="http://docs.ubuntu.com/maas/" rel="noreferrer" target="_blank">http://docs.ubuntu.com/maas/</a>> (woefully<br>
inconsistent). It would also be much harder to implement a reliable<br>
search function across any site including its docs.<br></blockquote><div><br></div><div>The idea is to improve upon what we have, not to achieve perfection. As you know, there are pros and cons to any design.<br></div><div><br></div><div>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.</div><div><br></div><div>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. <a href="http://docs.ubuntu.com/maas">docs.ubuntu.com/maas</a>) so that it retains some "loyalty" to the parent site (e.g. <a href="http://maas.io">maas.io</a>) all the while maintaining the foundation of a central theme. I believe I just described your second option.</div><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Second, scope. While the sites for each of these projects currently have<br>
a “Docs” section (indeed, Landscape has two), there won’t always be a<br>
clear distinction between what counts as as “docs” and what does not. A<br>
simple example is that “Get started with MAAS 2.0”<br>
<<a href="https://maas.io/get-started" rel="noreferrer" target="_blank">https://maas.io/get-started</a>> is a document, in that it would be<br>
perfectly useful if you printed it out. But it is also of primary<br>
importance on the site, and contains minor interactive elements<br>
(copyable command lines). Similarly you could imagine a walkthrough<br>
document that starts by prompting you for the name of your package, then<br>
fills in sample commands including that package name. A single element<br>
that couldn’t be implemented in Markdown would, apparently, result in<br>
the document having to be hosted separately from all the others.<br></blockquote><div><br></div><div>If we need to write something in HTML in the Markdown files then we can do so. The parser handles this fine. Fake News!!</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">(There are minor problems too, mainly involving the ways that browsers<br>
and search engines would treat <a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a> as a separate Web site.)<br></blockquote><div><br></div><div>Please elaborate. I'm not a web guy.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Finally, this statement —<br>
>…<br>
<span class="gmail-">> the help wiki, which is not documentation.<br>
</span>>…<br>
is bewildering. Of course the help wiki is documentation. It’s an<br>
unfortunate administrative quirk that <a href="http://help.ubuntu.com" rel="noreferrer" target="_blank">help.ubuntu.com</a> has two sets of<br>
documents, each covering much of the same topics. But moving one set to<br>
a separate site would make things worse: for example, it would break the<br>
search.<br></blockquote><div><br></div><div>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 <a href="http://help.ubuntu.com">help.ubuntu.com</a> with "Community Help Wiki".</div><div><br></div><div>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.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I suggest instead finding a way to get the doc builder to generate pages<br>
that can be inserted into existing project sites, so that they can be<br>
indexed and navigated in the same way as the rest of the site.<br></blockquote><div><br></div><div>This is a reiteration of your option #1 which I acknowledged earlier.</div><div><br></div><div>Peter</div></div></div></div>