Quantcast

Feedback request | Documentation site reorg, switch to Markdown

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
27 messages Options
12
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
All,

This is a request for feedback from the community.

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.

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.

For help.ubuntu.com, each help topic (Server, Desktop, and
Installation Guide) would get their own page (e.g.
docs.ubuntu.com/server). help.u.c would continue to exist solely for
the help wiki, which is not documentation.

All this would entail:

- Initial conversion of all XML files to GFM (GitHub Flavored
Markdown) [1]. Done by Canonical.
- New and actively maintained doc builder [2]
- Streamlined build and publication processes
- A common theme
- Contributions from the Canonical Docs Team members to the current
help.u.c projects (personal time)
- Multiple build formats across the board (where appropriate)

For contributors, workflow changes would be:

- Write in Markdown
- Use a different build tool (local building to verify HTML)

It is my hope that moving to Markdown will act as a catalyst to get
people to contribute to docs again. It is certainly more user-friendly
than the two forms of XML currently in use.

Launchpad and Bazaar will continue to be used for the current help.u.c
topics, mostly due to translations.

Canonical could create a mockup site of the Server Guide to show what
all this would look like, including at the commit, build, and publish
levels.

Note that documentation for the Canonical-sponsored projects is
available for contributions from the community (minus
internationalization at this time) and will be published according to
CC BY-SA 4.0 [3].

Thanks for listening,


--
Peter Matulis,
Documentation
Canonical Ltd.


[1]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
[2]: https://github.com/CanonicalLtd/documentation-builder
[3]: https://creativecommons.org/licenses/by-sa/4.0/

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
To reach a wide audience on this matter I sent to a few mailing lists.
Apologies in advance for any collateral damage this may cause.

Peter

On Wed, Feb 15, 2017 at 4:58 PM, Peter Matulis
<[hidden email]> wrote:

> All,
>
> This is a request for feedback from the community.
>
> 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.
>
> 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.
>
> For help.ubuntu.com, each help topic (Server, Desktop, and
> Installation Guide) would get their own page (e.g.
> docs.ubuntu.com/server). help.u.c would continue to exist solely for
> the help wiki, which is not documentation.
>
> All this would entail:
>
> - Initial conversion of all XML files to GFM (GitHub Flavored
> Markdown) [1]. Done by Canonical.
> - New and actively maintained doc builder [2]
> - Streamlined build and publication processes
> - A common theme
> - Contributions from the Canonical Docs Team members to the current
> help.u.c projects (personal time)
> - Multiple build formats across the board (where appropriate)
>
> For contributors, workflow changes would be:
>
> - Write in Markdown
> - Use a different build tool (local building to verify HTML)
>
> It is my hope that moving to Markdown will act as a catalyst to get
> people to contribute to docs again. It is certainly more user-friendly
> than the two forms of XML currently in use.
>
> Launchpad and Bazaar will continue to be used for the current help.u.c
> topics, mostly due to translations.
>
> Canonical could create a mockup site of the Server Guide to show what
> all this would look like, including at the commit, build, and publish
> levels.
>
> Note that documentation for the Canonical-sponsored projects is
> available for contributions from the community (minus
> internationalization at this time) and will be published according to
> CC BY-SA 4.0 [3].
>
> Thanks for listening,
>
>
> --
> Peter Matulis,
> Documentation
> Canonical Ltd.
>
>
> [1]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
> [2]: https://github.com/CanonicalLtd/documentation-builder
> [3]: https://creativecommons.org/licenses/by-sa/4.0/

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Milo Casagrande-2
> On Wed, Feb 15, 2017 at 4:58 PM, Peter Matulis
> <[hidden email]> wrote:
>
> For help.ubuntu.com, each help topic (Server, Desktop, and
> Installation Guide) would get their own page (e.g.
> docs.ubuntu.com/server). help.u.c would continue to exist solely for
> the help wiki, which is not documentation.

Just to be clear: this would mean that everything under lp:ubuntu-docs
would be converted to github-markdown, right?
Would that include other Ubuntu flavors?

(disclaimer: I'm not involved in the Ubuntu Docs team, so what I'm
saying might be wrong or not true anymore)
IIRC, some parts of the Ubuntu documentation are shared with/based on
GNOME documentation; if ubuntu-docs were to switch to a Markdown-based
syntax as the primary choice for writing documentation, I think it
might get hard to contribute back or be able to use the work done by
GNOME.

So, would this [xml|mallard]→Markdown conversion be final, or would it
still be possible to work with [xml|mallard] and convert it to
Markdown when necessary?
I'm trying to figure out how the workflow would be...

> - Initial conversion of all XML files to GFM (GitHub Flavored
> Markdown) [1]. Done by Canonical.
> - New and actively maintained doc builder [2]
> - Streamlined build and publication processes
> - A common theme
> - Contributions from the Canonical Docs Team members to the current
> help.u.c projects (personal time)
> - Multiple build formats across the board (where appropriate)
>
> For contributors, workflow changes would be:
>
> - Write in Markdown
> - Use a different build tool (local building to verify HTML)

What about translations?
Is there already a markdown-2-po extractor? Personally I've never seen
one, but I also haven't looked for one.

Ciao.

--
Milo Casagrande <[hidden email]>

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Stephen M. Webb-4
In reply to this post by Peter Matulis-5
On 2017-02-16 07:42 AM, Chris Perry wrote:

>
> I'm a newish volunteer so perhaps I can be trusted to give a new
> volunteer's opinion of Markdown. To me it's just a markup language. If
> I'm writing or revising a numbered list or creating a section heading
> or creating a table, etc, it makes little difference to me whether
> it's in Markdown or another markup language. I don't particularly like
> any markup language. I'd be able to work faster if we had a
> well-designed GUI front-end that hid most of the details of the markup
> language.
>
> It's not clear to me that Peter's proposal has significant benefits
> for users of the documentation or people who want to contribute to the
> documentation. In my opinion Peter has to provide very strong evidence
> of significant benefits to get this approved.

Switching from a semantic documentation markup to a non-semantic unstructured set of HTML macros that has wretched
support for anything other than web pages is a net negative gain. Markdown was written by coders for coders so they can
appear to have something like online documentation.  It's the wrong choice for something like a manual, API docs, or
pretty much anything more than marketing quips or blog comments.

I'm all for a consistent presentation style across Canonical-supported media and across all Ubuntu media.  I don't think
ex-cathedra forcing a workflow and markup switch onto actual writers is the right way to achieve that if you're trying
to encourage participation and quality of content.

So, agreed, I'd like to see a community-friendly discussion on the benefits of moving away from existing workflows and
structure with arguments pro and contra.

--
Stephen M. Webb  <[hidden email]>

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Jeremy Bicha-2
On Thu, Feb 16, 2017 at 8:25 AM, Stephen M. Webb
<[hidden email]> wrote:
> Switching from a semantic documentation markup to a non-semantic unstructured set of HTML macros that has wretched
> support for anything other than web pages is a net negative gain. Markdown was written by coders for coders so they can
> appear to have something like online documentation.  It's the wrong choice for something like a manual, API docs, or
> pretty much anything more than marketing quips or blog comments.

I'm guessing that the new format will work fine for the Server Guide.

But I'm not sure that it will work as well for the Desktop help which
is a lot more visual and has pictures. For instance, this page:

https://help.ubuntu.com/stable/ubuntu-help/unity-introduction.html
https://help.gnome.org/users/gnome-help/stable/shell-introduction.html

How does your proposal handle that Ubuntu (Unity) currently ships the
Desktop help in the yelp Help viewer which is also used by other GNOME
apps?

I suggest that someone let the GNOME docs team know about this proposal.

Thanks,
Jeremy Bicha

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Gunnar Hjalmarsson
In reply to this post by Peter Matulis-5
[ Replying to the lists I'm subscribed to. Now when the topic has been
announced to multiple lists, I would suggest that the following
discussion is hold on one list, and I suggest ubuntu-doc for the purpose. ]

Hi Peter,

There are three sets of docs at help.ubuntu.com:

* installation guide
* server guide
* desktop guide

Installation guide
------------------
This guide is provided via the installation-guide package, which origins
from Debian, and the published pages are built from that package. It
would make little sense to me to do something else on the Ubuntu side.

Server guide
------------
This guide is currently written in the DocBook XML format, and
translated to a few languages. Others know more about it, so I won't
comment on it further.

Desktop guide
-------------
This guide is currently written in the Mallard XML format. It consists
of about 300 pages which are linked together in an intelligent manner
which provides a reasonable browsing hierarchy. The desktop guide is
translated into 25-30 languages with a decent coverage.

I'm disinclined to support a switch to some other markup language for
these reasons:

1. Mallard serves its purpose well, and the established procedures for
maintaining and publishing the guide work smoothly.

2. GNOME uses it, which gives us a free ride for the maintenance of many
pages which are identical or almost identical. I noticed that both Milo
and Jeremy mentioned this aspect.

3. I fear that a transition to some other markup language, new build
procedures etc. would mean a lot, really a lot of work. Besides the fact
that it's unclear to me who would do it, I fail to see that it would
result in a significantly better documentation or significantly less
work going forward. I simply don't think it would be worth it.


As regards the domain name, it would be doable to move it to
docs.ubuntu.com. It's not apparent to me, though, that the desktop
guide, which targets not-so-tech-savvy end users, would fit so well at
doc.ubuntu.com, which currently is made up of technically advanced stuff
targeting sys admins and package developers. And if we would change the
domain, it's very important that we set up proper redirects from the old
location, so we don't break the many thousand links out there.

"Consistent look and feel" sounds good, and the most important aspect of
that IMO is what the top of the pages look like. We have adapted to the
overall Ubuntu design before, and we can do it again if appropriate
without changing the underlying markup language and build procedures.


So, my gut feeling is that alternative tools should be considered when
starting new sets of docs, for instance the Unity 8 documentation.
Changing tools and procedures for already existing documentation, OTOH,
requires convincing justification. I'm not convinced at this time.

--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

RE: Feedback request | Documentation site reorg, switch to Markdown

Doug Smythies
In reply to this post by Peter Matulis-5
Hi Robert,

Thanks very much for chiming in.

On 2017.02.18 15:30 Robert Young wrote:

> Hi all,
>
> As a person interested in contributing for the first time,

Do you know which area you are most likely to contribute to?
The desktop help or the serverguide or the installation guide
or all 3?

> I think there
> would be a significant benefit to working in markdown. Markdown has a
> large user base as the use of it in github and BitBucket has increased.
> It is a markup language that gets out of your way and lets you focus on
> the content. Plus it lends itself to version control very well.

... Doug
 


--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

RE: Feedback request | Documentation site reorg, switch to Markdown

Doug Smythies
In reply to this post by Peter Matulis-5
Hi Peter,

I'm only commenting on the Ubuntu Serverguide herein,
As others have covered the desktop help docs and the
installation guide quite well.

What I have to say was also covered in our off-list
pre-discussion.

On 2017.02.15 13:58 Peter Matulis wrote:

> All this would entail:
>
> - Initial conversion of all XML files to GFM (GitHub Flavored
> Markdown) [1]. Done by Canonical.
>
> Canonical could create a mockup site of the Server Guide to show what
> all this would look like, including at the commit, build, and publish
> levels.

For years now, you have been trying get agreement to change the
the serverguide to some sort of markdown. I have always wanted to
see a project plan, timeline, and labour estimate. Now you are saying
Canonical would do the initial work (I assume they would want
a project plan, timeline and estimate), so that community concern
is removed.

Would the mentioned mockup site and workflow include translations
workflow? Would it include a PDF mockup serverguide? In my opinion
a PDF serverguide is a must have.

> It is my hope that moving to Markdown will act as a catalyst to get
> people to contribute to docs again. It is certainly more user-friendly
> than the two forms of XML currently in use.

As I have said so many times now, the Serverguide is in
desperate need of subject matter expert help.

Myself, I don't think the change would make any difference to
people's wiliness to contribute. However the feedback
from Robert Young suggests perhaps otherwise.

> Note that documentation for the Canonical-sponsored projects is
> available for contributions from the community (minus
> internationalization at this time) and will be published according to
> CC BY-SA 4.0 [3].

Good.



--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
On Sun, Feb 19, 2017 at 2:25 PM, Doug Smythies <[hidden email]> wrote:

> On 2017.02.15 13:58 Peter Matulis wrote:
>
>> All this would entail:
>>
>> - Initial conversion of all XML files to GFM (GitHub Flavored
>> Markdown) [1]. Done by Canonical.
>>
>> Canonical could create a mockup site of the Server Guide to show what
>> all this would look like, including at the commit, build, and publish
>> levels.
>
> For years now, you have been trying get agreement to change the
> the serverguide to some sort of markdown. I have always wanted to
> see a project plan, timeline, and labour estimate. Now you are saying
> Canonical would do the initial work (I assume they would want
> a project plan, timeline and estimate), so that community concern
> is removed.
>
> Would the mentioned mockup site and workflow include translations
> workflow? Would it include a PDF mockup serverguide? In my opinion
> a PDF serverguide is a must have.

Yes, it would include translations.

Yes, it would include a PDF.

>> It is my hope that moving to Markdown will act as a catalyst to get
>> people to contribute to docs again. It is certainly more user-friendly
>> than the two forms of XML currently in use.
>
> As I have said so many times now, the Serverguide is in
> desperate need of subject matter expert help.

Yes, I know. :(

> Myself, I don't think the change would make any difference to
> people's wiliness to contribute. However the feedback
> from Robert Young suggests perhaps otherwise.

The argument about how the GNOME project uses XML is significant.
There was something said about the help facility included on the
desktop image. I'm not sure how that fits in but apparently moving to
Markdown will interfere. I don't understand the statement that
"Markdown doesn't work well with images" but I don't need to know
since there are enough reasons to keep the Desktop on XML.

I believe we still have a chance to revive the Server Guide however.
No, I do not have any scientific proof or psychological studies done
that will guarantee that Markdown will make things better but I don't
think we need to worry since contributions have been so low these last
few years. I'll start the SG mockup project.

As for the Installation Guide, it could benefit from being part of the
family. I'll inquire into the feasibility of converting it.

Apart from workflow and build procedures there is still the question
of appearances. Even if one, two, or all three projects (D, S, IG)
remains as they are there is value (I believe) in herding them
together (theme and URL space). I'll look into the possibility of
doing this.

Any objections?

Peter Matulis

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Colin Watson
On Sun, Feb 19, 2017 at 07:38:13PM -0500, Peter Matulis wrote:
> As for the Installation Guide, it could benefit from being part of the
> family. I'll inquire into the feasibility of converting it.

The installation guide is substantially based on Debian's; it's been a
little while since it was merged up, but it's not terribly out of date,
and it would of course be nearly impossible to keep merged if there were
a format translation in the way.

--
Colin Watson                                       [[hidden email]]

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Louis Bouchard-2
In reply to this post by Peter Matulis-5
Hello,

Le 20/02/2017 à 12:29, Chris Perry a écrit :

> Hi Peter
>
> It sounds as if you and Doug agree that the main problem here - by far
> the most important problem? - (as regards the server guide) is that
> "the Serverguide is in desperate need of subject matter expert help".
> Your proposal does nothing directly to address this problem. I don't
> understand this. If we get the technical reviews then if necessary I
> can help Doug do the updates to the server guide, Can't Canonical
> provide the technical reviewers? Perhaps I'm misunderstanding
> something crucial?
>
> Regards,
>
> Chris.
>
>

I have contributed to a few sections of the Server guide and would be happy to
continue. But since this is not my dayjob, having to re-ramp up the XML editing
knowledge,find some "workable" XML editor, remember the intricacies of the
edition process simply often too time consuming to participate.

I don't have any favorite and I don't think that writing things that will later
be handled by tech writers either. But it ought to be simpler to create
documents than fighting with XML.

MTCW,

...Louis


--
Louis Bouchard
Software engineer, Cloud & Sustaining eng.
Canonical Ltd
Ubuntu developer                       Debian Maintainer
GPG : 429D 7A3B DD05 B6F8 AF63  B9C4 8B3D 867C 823E 7A61

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Hannie Dumoleyn
Op 20-02-17 om 16:02 schreef Louis Bouchard:

> Hello,
>
> Le 20/02/2017 à 12:29, Chris Perry a écrit :
>> Hi Peter
>>
>> It sounds as if you and Doug agree that the main problem here - by far
>> the most important problem? - (as regards the server guide) is that
>> "the Serverguide is in desperate need of subject matter expert help".
>> Your proposal does nothing directly to address this problem. I don't
>> understand this. If we get the technical reviews then if necessary I
>> can help Doug do the updates to the server guide, Can't Canonical
>> provide the technical reviewers? Perhaps I'm misunderstanding
>> something crucial?
>>
>> Regards,
>>
>> Chris.
>>
>>
> I have contributed to a few sections of the Server guide and would be happy to
> continue. But since this is not my dayjob, having to re-ramp up the XML editing
> knowledge,find some "workable" XML editor, remember the intricacies of the
> edition process simply often too time consuming to participate.
>
> I don't have any favorite and I don't think that writing things that will later
> be handled by tech writers either. But it ought to be simpler to create
> documents than fighting with XML.
>
> MTCW,
>
> ...Louis
>
>
Just my 2 cents. Would it be possible to let contributors hand in their
documents in plain text and let the XML experts in our team do the XML
editing?

Hannie


--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Matthew Paul Thomas
In reply to this post by Peter Matulis-5
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.

It’s true that this would let people work on different projects using
the same processes. Others have responded about that.

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.

(I’m speaking as a designer who has contributed to Ubuntu help in the
distant past, and who may work on developer UI and reference materials
in the near future.)

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

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.

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

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.

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.

Cheers
--
mpt

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5


On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas <[hidden email]> 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

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Peter Matulis-5
On Mon, Feb 20, 2017 at 5:14 PM, Chris Perry <[hidden email]> wrote:

I've never worked on the server guide until today but it was
straightforward for me to set it up, do a simple edit to one of the
xml files

Yes, I know it's simple to do a simple edit.

Seriously though, I've done a fair amount of writing for the Server Guide myself, but like almost every contributor I've talked to over the years, I end up conceding that it's really a PITA to work with. It simply gets in the way of writing and, like another past contributor mentioned in this thread, you end up with an imposing "ramp-up" wall when one wants to dive back in.

I have talked to people who have made very significant additions to the guide. These are topics that are complex and extremely valuable to capture. Yet they have told me, in no uncertain terms, that they will never do so again, simply because of the XML. These are very bright people, but still they reject the underlying format.

<sect8 id="personal rant begins">

For the benefit of everyone following along, let's look at an example using a "easy" snippet of text from the guide:
    <sect2 id="multipath-config-overview">
      <title id="config-overview-title">Configuration File Overview</title>

      <para>The multipath configuration file is divided into the following
      sections:</para>

      <variablelist>
        <varlistentry>
          <term><emphasis role="bold">blacklist</emphasis></term>

          <listitem>
            <para>Listing of specific devices that will not be considered for
            multipath.</para>
          </listitem>
        </varlistentry>
There are at least 10 "things" here to know in order to do something very simple.

Here's something more complex from the same file. I admit that this could have been written in a more orderly fashion but this shows the potential extent of the ugliness awaiting any intrepid traveler:
    <sect2 id="multipath-device-identifiers">
      <title>Multipath Device Identifiers</title>

      <para>Each multipath device has a World Wide Identifier (WWID), which is
      guaranteed to be globally unique and unchanging. By default, the name of
      a multipath device is set to its WWID. Alternately, you can set the
      <emphasis role="bold"><link
      linkend="attribute-user_friendly_names">user_friendly_names</link>
      </emphasis>option in the multipath configuration file, which causes
      DM-Multipath to use a node-unique alias of the form <emphasis
      role="bold">mpathn</emphasis> as the name. For example, a node with two
      HBAs attached to a storage controller with two ports via a single
      unzoned FC switch sees four devices: <emphasis
      role="bold">/dev/sda</emphasis>, <emphasis
      role="bold">/dev/sdb</emphasis>, <emphasis
      role="bold">/dev/sdc</emphasis>, and <emphasis
      role="bold">/dev/sdd</emphasis>. DM-Multipath creates a single device
      with a unique WWID that reroutes I/O to those four underlying devices
      according to the multipath configuration. When the <emphasis
      role="bold"><link
      linkend="attribute-user_friendly_names">user_friendly_names</link></emphasis>
      configuration option is set to <emphasis role="bold">yes</emphasis>, the
      name of the multipath device is set to <emphasis
      role="bold">mpathn</emphasis>. When new devices are brought under the
      control of DM-Multipath, the new devices may be seen in two different
      places under the <emphasis role="bold">/dev</emphasis> directory:
      <emphasis role="bold">/dev/mapper/mpathn</emphasis> and <emphasis
      role="bold">/dev/dm-n</emphasis>. <itemizedlist>
          <listitem>
            <para>The devices in <emphasis role="bold">/dev/mapper</emphasis>
            are created early in the boot process. Use these devices to access
            the multipathed devices, for example when creating logical
            volumes.</para>
          </listitem>

          <listitem>
            <para>Any devices of the form <emphasis
            role="bold">/dev/dm-n</emphasis> are for internal use only and
            should never be used.</para>
          </listitem>
        </itemizedlist>For information on the multipath configuration
      defaults, including the <emphasis role="bold"><link
      linkend="attribute-user_friendly_names">user_friendly_names</link></emphasis>
      configuration option, see Section , <link
      linkend="multipath-config-defaults">Configuration File
      Defaults</link>. You can also set the name of a multipath device to a
      name of your choosing by using the <emphasis role="bold"><link
      linkend="attribute-alias">alias</link></emphasis> option in the
      <emphasis role="bold">multipaths</emphasis> section of the multipath
      configuration file. For information on the <emphasis
      role="bold">multipaths</emphasis> section of the multipath configuration
      file, see Section, <link
      linkend="multipath-config-multipath">Multipaths Device Configuration
      Attributes</link>.</para>
    </sect2>
I should mention to the uninitiated that a single wayward character will generate a bewildering error when a build of HTML is attempted. Considering that you need to go through a long file full of the above stuff, I recall my "debugging" sessions consuming a large amount of my time, not to mention the frustration.

</sect8>

anyone who is willing to do a series of contributions can learn either [XML or MD] easily enough. We have
xml for the server guide at present so why expend the effort to switch to Markdown?

See above. Also, historically, an extremely high percentage of contributions are reviews and corrections. This is easy to achieve with XML precisely because it involves touching the XML very little, if at all. Although this type of help is very valuable, what we're discussing here, I hope, is how we can get people to actually write new stuff.

Is there ANYONE out there that has written a significant amount of material for the Server Guide and also believes we should stick with XML/Docbook? These are the people I especially want to hear from.

I believe that XML is technically superior to Markdown and it definitely has advantages, but only when used in certain contexts. A good example is a single author, or a team of dedicated people, writing for a project, like an O'Reilly book, for instance. However, our contributors come and go. Each wants to help but very few will take the time to understand a difficult format unless they expect to do sustained writing. This is just not our reality. What we're trying to solve here is:

Find a format that the average person can use to write new material for Ubuntu Server without having to devote an inordinate amount of time learning compared to the time they will spend writing.

I'd like to say that I am speaking as a community member. Everything I've said above I've believed years ago, before I was a member of the Canonical documentation team. At this time, however, the bonus is that there is a chance to improve things at an organizational level as well (explained in my initial post). It seems logical therefore to choose a format that the other Canonical projects use. We chose Markdown for a reason too (and we *are* a dedicated team of people)!

Peter

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Stephen M. Webb-4
On Thu, Feb 16, 2017 at 8:25 AM, Stephen M. Webb <[hidden email]> wrote:

Switching from a semantic documentation markup to a non-semantic unstructured set of HTML macros that has wretched
support for anything other than web pages is a net negative gain. Markdown was written by coders for coders so they can
appear to have something like online documentation.  It's the wrong choice for something like a manual, API docs, or
pretty much anything more than marketing quips or blog comments.

Here are two sites I know that use Markdown for technical documentation:


Is there something wrong with them?

There is more, however, to consider than visual results. A choice of format impacts source text readability and ease of use. I am intimately familiar with both the Ubuntu Server Guide as well as both the above projects and I can tell you that at least Juju documentation has more non-Canonical contributors than the Server Guide. This is an important fact, especially when you consider that Juju is a tiny niche project.

I'm all for a consistent presentation style across Canonical-supported media and across all Ubuntu media.  I don't think
ex-cathedra forcing a workflow and markup switch onto actual writers is the right way to achieve that if you're trying
to encourage participation and quality of content.

I don't see any "ex-cathedra forcing" and "markup switch" going on. This email thread, with the word "feedback request" in its subject and "proposal" in its second sentence, was sent as far and wide as it possibly could. There is a lot of discussing going on too.

Peter 

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Jeremy Bicha-2
On Thu, Feb 16, 2017 at 8:46 AM, Jeremy Bicha <[hidden email]> wrote:

Hi Jeremy. It's good to hear from you.

I'm guessing that the new format will work fine for the Server Guide.

This means a lot coming from someone who did a lot of work maintaining the Server Guide in the past.
 
But I'm not sure that it will work as well for the Desktop help which
is a lot more visual and has pictures. For instance, this page:

https://help.ubuntu.com/stable/ubuntu-help/unity-introduction.html
https://help.gnome.org/users/gnome-help/stable/shell-introduction.html

How does your proposal handle that Ubuntu (Unity) currently ships the
Desktop help in the yelp Help viewer which is also used by other GNOME
apps?

I suggest that someone let the GNOME docs team know about this proposal.

These are good points that were addressed in another post. I concede that the Desktop is not a good fit for a change of format.

Peter 

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Matthew Paul Thomas
In reply to this post by Peter Matulis-5
Peter Matulis wrote on 23/02/17 00:03:

>
> On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas <[hidden email]
>…
>> 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.

For sure. Imperfection is not my claim. My claim is that it would be
worse than what we have.

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

I know they’re good. I work right next to them. This month I’ve been
working with them. But no matter how good a team is, some things are
much harder than others, some things are naturally prioritized ahead of
others, and some things never get done. You can’t help but remind me of
the bureaucrat who reassures Indiana Jones that “Top Men” are working on
the soon-to-be-forgotten Ark of the Covenant.

As a demonstration, see <https://insights.ubuntu.com/>. Despite the best
of intentions, after four and a half years, the Web team still have not
quite managed to make it consistent with <https://www.ubuntu.com/>. It’s
similar enough that you can tell the differences are accidental, rather
than deliberate: a different logo rendering, a differently styled search
field returning unhelpfully different results (how am I supposed to know
whether the info I want is an “insight” or not?), even an
unintentionally different shade of orange.

That case was more excusable because it was a new site, with a dynamic
CMS, for new materials. Moving existing, static materials to a separate
site is what is so egregious 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.

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.

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.

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.

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

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

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.

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

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.

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.

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?”

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.

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

--
mpt

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Peter Matulis-5


On Fri, Feb 24, 2017 at 9:11 AM, Douglas Stanley <[hidden email]> wrote:
Hi, mostly long time lurker here.

I feel like there's an argument about getting new documentation written by SME's and that markdown is easier to get into.

I have to agree that markdown is really pretty easy to pick up and can be written on a headless server over ssh with vim and visually look good as you're writing it.

I also get that there are style guidelines to adhere to and that the docbook XML is best suited to do just that.

What if documentation could be written by people who know the content in the format their comfortable with, say markdown or reStructuredText, then use something like pandoc to convert their work into the appropriate docbook XML? I know pandoc has a way to use templates if you want to customize the output too. So if your docbook is not vanilla, a template can be created to convert things into your specific docbook flavor.

Create sort of a pipeline system. Have a git repo where people can submit their markdown and then it gets massaged into appropriate docbook XML by those who are the docbook experts.

I know it's not quite ideal, but both sides of the argument can get what they want. Just a thought I had.


Hi Doug, thanks for speaking out, and nice to meet you.

Your idea is interesting. The main problem, though, is the lack of human resources required. There are only a couple of people who inspect all incoming contributions, which are, like I said before, primarily reviews and corrections. So an increase in actual new content in addition to an extra step of converting to XML is unimaginable.

Peter


 

--
ubuntu-translators mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Matthew Paul Thomas


On Thu, Feb 23, 2017 at 3:03 PM, Matthew Paul Thomas <[hidden email]> 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
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
12
Loading...