<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Feb 23, 2017 at 3:03 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 23/02/17 00:03:<br>
<span class="gmail-">><br></span><span class="gmail-">> The idea is to improve upon what we have, not to achieve perfection.<br>
<br>
</span>For sure. Imperfection is not my claim. My claim is that it would be<br>
worse than what we have.</blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br></blockquote><div><br></div><div>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.<br></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">
<span class="gmail-"><br>
> Your first option (your preferred I'm presuming) is to simply<br>
> integrate docs into a project's website (a traditional design). This<br>
> has downsides too: every doc project would have its own branding,<br>
> losing the advantage of a consistent "doc theme" that users will most<br>
> likely prefer as they jump from Juju to MAAS to Landscape,<br>
> technologies that are often used in tandem.<br>
<br>
</span>So we disagree about what’s more important: consistency between<br>
documentation of different products, vs. consistency of a product’s<br>
documentation with the rest of the product’s pages.<br>
<br></blockquote><div><br></div><div>Lower down I proposed a compromise.</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"><br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I think consistency between documentation of different products is less<br>
important, because the number of interactive elements is tiny. It’s not<br>
as if you’ll click on the wrong button because the buttons are placed<br>
differently in Maas docs than in Landscape docs, or that you’ll fail to<br>
recognize a checkbox because it’s styled differently in the Juju docs<br>
than the Ubuntu Core docs. They contain nary a button or checkbox in the<br>
first place! If we were talking about signup forms, or checkouts, or<br>
video players, that would be a better argument.</blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br></blockquote><div><br></div><div>I think people spend a lot of time reading (and revisiting) documentation.<br></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">
<br>
And I think consistency between documentation and the rest of the pages<br>
about a product is more important, because (as I said before) while some<br>
things may be definitely “documentation” and some definitely not, other<br>
pages will live in a fuzzy area between the two. Having “Docs” as a<br>
category is a common mistake, but still a mistake — like when a company<br>
categorizes its wares into “Products” and “Solutions”, because they know<br>
which is which, and they haven’t realized that nobody else does.<br>
<br></blockquote><div><br></div><div>IMO, there's nothing wrong with a link that points to documentation. </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"><br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Even if I’m wrong about all that — even if “Docs” are a clear and<br>
definite thing, and there are people who really really want their Juju<br>
and Ubuntu Core and Maas documents to have a consistent theme — they<br>
could just use <a href="http://readthedocs.org" rel="noreferrer" target="_blank">readthedocs.org</a>, which would do a far better job than<br>
<a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a> simply because it *also* documents thousands of other,<br>
non-Ubuntu-specific projects a developer might be jumping between.<br>
<span class="gmail-"><br></span></blockquote><div><br></div><div>That's a new idea.</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"><br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-">> We can always tweak each project's subpage (e.g.<br>
</span>> <a href="http://docs.ubuntu.com/maas" rel="noreferrer" target="_blank">docs.ubuntu.com/maas</a> <<a href="http://docs.ubuntu.com/maas" rel="noreferrer" target="_blank">http://docs.ubuntu.com/maas</a>>) so that it retains<br>
> some "loyalty" to the parent site (e.g. <a href="http://maas.io" rel="noreferrer" target="_blank">maas.io</a> <<a href="http://maas.io" rel="noreferrer" target="_blank">http://maas.io</a>>) all<br>
<span class="gmail-">> the while maintaining the foundation of a central theme. I believe I<br>
> just described your second option.<br>
><br>
> In terms of search, your first option gains the ability to scan the<br>
> rest of the project's non-docs but you also lose the ability to search<br>
> across multiple doc projects which is something we're planning. For<br>
> the aforementioned technologies, and soon others, this is a much more<br>
> powerful feature IMO.<br>
<br>
</span>If “soon others” includes Snapcraft, you’ll need to combine search<br>
results from multiple sites anyway (because Snapcraft docs will stay off<br>
<a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a>).<br>
<span class="gmail-"><br></span></blockquote><div><br></div><div>I'm not sure which technologies will come next.</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"><br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-">> If we need to write something in HTML in the Markdown files then we<br>
> can do so. The parser handles this fine. Fake News!!<br>
<br>
</span>The copyable command lines involve an external JavaScript file, so it<br>
wouldn’t be just a matter of inserting HTML — unless you expected and<br>
allowed inlining of scripts into the HTML.<br>
<span class="gmail-"><br></span></blockquote><div><br></div><div>I've been told it's possible.</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"><span class="gmail-">
>> (There are minor problems too, mainly involving the ways that<br>
>> browsers and search engines would treat <a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a><br>
</span>>> <<a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">http://docs.ubuntu.com</a>> as a separate Web site.)<br>
<span class="gmail-">><br>
> Please elaborate. I'm not a web guy.<br>
<br>
</span>One example is that if you search Google for “Maas”, the relevant search<br>
result includes direct links to the “Get started”, “Tour”, and “How it<br>
works” sections — but not to the “Docs” section, because it is (as far<br>
as Google can tell) on a different site.<br>
<br></blockquote><div><br></div><div>Thanks. You've just provided ammunition to help me get rid of those documents. I don't like them.</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">
A second example is that for any product, if you set your browser’s zoom<br>
level on its <a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a> pages, it won’t carry over to the rest of<br>
the site, or vice versa.<br>
<br></blockquote><div><br></div><div>Ok</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">
A third example is that any UI that arranges pages by site — like<br>
Safari’s tab switcher, or most browsers’ history windows — will assume<br>
that a product’s <a href="http://docs.ubuntu.com" rel="noreferrer" target="_blank">docs.ubuntu.com</a> pages are a separate site.<br>
<br></blockquote><div><br></div><div>Ok</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">
As I said, minor problems, but symptoms of the weird IA involved.<br>
<span class="gmail-"><br>
>> Finally, this statement —<br>
>> >…<br>
>> > the help wiki, which is not documentation.<br>
>> >…<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<br>
>> to a separate site would make things worse: for example, it would<br>
>> break the search.<br>
><br>
> There was some history bundled into my statement. It was agreed at a<br>
> community doc meeting a while ago (2014?) that we would no longer<br>
> consider the Ubuntu help wiki to be documentation. The reasoning was<br>
> that documentation is more than text published on a web site. It has<br>
> to meet certain criteria, like being subject to peer reviews and<br>
> having a reasonable degree of maintenance applied (the official<br>
> documentation has this). One concrete action resulting from this<br>
> decision was to replace the header of "Community Documentation" on<br>
> <a href="http://help.ubuntu.com" rel="noreferrer" target="_blank">help.ubuntu.com</a> with "Community Help Wiki".<br>
<br>
</span>“Who are you gonna believe, the minutes of a Community Documentation<br>
Team meeting from 2014, or your lying eyes?”<br>
<br></blockquote><div><br></div><div>I was merely providing context to my assertion. That it wasn't only my belief but the belief of others as well.</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">
If we’re going to cast into history, I’ll go back further: to July 2006,<br>
when I included “documentation” on a list of words to avoid in anything<br>
produced or overseen by the Documentation Team.<br>
<<a href="https://lists.ubuntu.com/archives/ubuntu-doc/2006-July/006669.html" rel="noreferrer" target="_blank">https://lists.ubuntu.com/<wbr>archives/ubuntu-doc/2006-July/<wbr>006669.html</a>><br>
<br>
The reason was that even if software developers see that word as a<br>
meaningful descriptor, end users do not. I can confidently predict that<br>
for end-user help, declaring that some pages are “documentation” — or<br>
even “official documentation” — and that others are not, will not have<br>
altered user behavior one iota.<br>
<span class="gmail-"><br></span></blockquote><div><br></div><div>As far as <a href="http://docs.ubuntu.com">docs.ubuntu.com</a> 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 <a href="http://help.ubuntu.com">help.ubuntu.com</a>.</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"><span class="gmail-">
> It's better that a set of search results points to either reliable<br>
> information or unreliable information, not a mix of the two. So it<br>
> actually makes sense to separate them, in terms of searching.<br>
</span>>…<br>
<br>
If it’s really “unreliable”, why host it at all?<br>
<span class="gmail-HOEnZb"><font color="#888888"><br></font></span></blockquote><div><br></div><div>I don't think we should get rid of the wiki. It has value for many people.</div><div><br></div><div>- People like a place to write stuff.<br></div><div>- 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.</div><div><br></div><div>There are indeed some good things to be found there.</div><div><br></div><div>Peter</div></div></div></div>