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

2017-02-22 Thread Peter Matulis 
On Thu, Feb 16, 2017 at 8:46 AM, Jeremy Bicha  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
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

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

2017-02-22 Thread Peter Matulis 
On Thu, Feb 16, 2017 at 8:25 AM, Stephen M. Webb  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:

https://jujucharms.com/docs
https://docs.ubuntu.com/maas

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
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

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

2017-02-22 Thread Peter Matulis 
On Mon, Feb 20, 2017 at 5:14 PM, Chris Perry 
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.



For the benefit of everyone following along, let's look at an example using
a "easy" snippet of text from the guide:

> 
>   Configuration File Overview
>
>   The multipath configuration file is divided into the following
>   sections:
>
>   
> 
>   blacklist
>
>   
> Listing of specific devices that will not be considered for
> multipath.
>   
> 
>
> 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:

> 
>   Multipath Device Identifiers
>
>   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
>  linkend="attribute-user_friendly_names">user_friendly_names
>   option in the multipath configuration file, which causes
>   DM-Multipath to use a node-unique alias of the formrole="bold">mpathn 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:role="bold">/dev/sda,role="bold">/dev/sdb,role="bold">/dev/sdc, androle="bold">/dev/sdd. 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 therole="bold">   
> linkend="attribute-user_friendly_names">user_friendly_names
>   configuration option is set to yes, the
>   name of the multipath device is set torole="bold">mpathn. When new devices are brought under the
>   control of DM-Multipath, the new devices may be seen in two different
>   places under the /dev directory:
>   /dev/mapper/mpathn androle="bold">/dev/dm-n. 
>   
> The devices in /dev/mapper
> are created early in the boot process. Use these devices to access
> the multipathed devices, for example when creating logical
> volumes.
>   
>
>   
> Any devices of the form  role="bold">/dev/dm-n are for internal use only and
> should never be used.
>   
> For information on the multipath configuration
>   defaults, including the
> linkend="attribute-user_friendly_names">user_friendly_names
>   configuration option, see Section ,linkend="multipath-config-defaults">Configuration File
>   Defaults. You can also set the name of a multipath device to a
>   name of your choosing by using thelinkend="attribute-alias">alias option in the
>   multipaths section of the multipath
>   configuration file. For information on therole="bold">multipaths section of the multipath configuration
>   file, see Section,linkend="multipath-config-multipath">Multipaths Device Configuration
>   Attributes.
> 
>
> 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.



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 disc

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

2017-02-22 Thread Peter Matulis 
On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas 
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.
>  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
>  vs.  (great!)
> with  vs.  (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”
>  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 re

Re: Japanese team (reviewer) is not working

2017-02-22 Thread BALLOON a.k.a. Fu-sen. 
Sorry, someone please arbitrate. That's why I appealed here.
Then, this will not solve anything.

-- 
ubuntu-translators mailing list
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

Re: Japanese team (reviewer) is not working

2017-02-22 Thread Fumihito YOSHIDA 
> Please understand the true meaning I have appealed here!
> I do not bother posting it here in English to want a reviewer!!

Sorry, but I have to follow our discipline, bad quality and license
violation are real disaster for us.

Again, Please provide your truth about past days, this is very
important for us. Your commits are not based web-translation,
right?

-- 
ubuntu-translators mailing list
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

Re: Japanese team (reviewer) is not working

2017-02-22 Thread BALLOON a.k.a. Fu-sen. 
Please understand the true meaning I have appealed here!
I do not bother posting it here in English to want a reviewer!!


BALLOON a.k.a. Fu-sen. (Keiichi SHIGA)
balloonakafu...@gmail.com
https://launchpad.net/~balloon

-- 
ubuntu-translators mailing list
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

Re: Japanese team (reviewer) is not working

2017-02-22 Thread Fumihito YOSHIDA 
> This is the result that you tried to keep it:
> https://launchpad.net/~ubuntu-l10n-ja/+members
>
> 2014 has not been added at the end. Are you still going to keep it?
> This seems to need to consider somewhat. I appealed to it for that.

Shortly, Yes. This result is not expected, but as prepared.

We still need our high bar for translators(=comitters), we can not
accept bad translations for Japanese users, sorry for limited
resource, but Japanese Translators(include me) are work as quality
gate, no one achieve our bar, so we can't scale, as intended.
But, you can contribute to Japanese Translations, because
non-translator contributors still smaller than Translators resources.
Please use our predefined way...

And, this is constatation for correction, you had not submit with
Web-based(license violated) translation yet in past days, is it right?

Regards,

-- 
ubuntu-translators mailing list
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

Re: Japanese team (reviewer) is not working

2017-02-22 Thread BALLOON a.k.a. Fu-sen. 
This is the result that you tried to keep it:
https://launchpad.net/~ubuntu-l10n-ja/+members

2014 has not been added at the end. Are you still going to keep it?
This seems to need to consider somewhat. I appealed to it for that.


BALLOON a.k.a. Fu-sen. (Keiichi SHIGA)
balloonakafu...@gmail.com
https://launchpad.net/~balloon

-- 
ubuntu-translators mailing list
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

Re: Japanese team (reviewer) is not working

2017-02-22 Thread Fumihito YOSHIDA 
Hi,

> However, since the quality of Web translation is also improving,
> it should not completely deny it.
> It improves translation improvement now.

  Partially yes, but I have to say "No" in Ubuntu Translations. We can
*not* use web based machine translation systems in FLOSS products,
that cause serious license issue, not (only) quality problem. If you
submit web-based machine translations at past-days, please revert
these outputs.

> However, it seems that it has refused participation of a new reviewer
> due to the influence which is sticking to quality too much.

  I must say "No", sorry. Because messy translations break the chance
of using user-side machine translations (with web-based translations)
.
  Please take care of itself.  Users can translate with machine
translation in their hands.

> Existing members will have a day to change one day.
> For that, we must have a new user.
> There is no user who can perfectly work perfectly...
> It is the same for everything. Both translators and communities...
>
> I am seeing many translations back in English with recent Ubuntu flavors.
> It is obviously a lack of reviewer. I hope to solve this problem at an
> early date.

  No, this is not only reviewers resources problem, that caused by
our(Japanese Team) policy: "If you find not good translation and you
done have enough time for brush-up, don't accept that."

Regards,

-- 
ubuntu-translators mailing list
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

Re: Japanese team (reviewer) is not working

2017-02-22 Thread BALLOON a.k.a. Fu-sen. 
Hi Yoshida-san,


First of all I thank you for your contribution to date.
The current Ubuntu flavors has been installed normally
so that Japanese desktop can be easily used.
That is a major factor that Japanese users including me continue to use Ubuntu.
ありがとうございます。(Thank you.)

I was feeling a sense of crisis really, so I am a bit relieved to this reaction.


I also feel about the quality of translation as I see it.
I have experienced many things that translations translated especially
from foreign users recently have to be revised again.
Especially translated texts translated from foreign users recently use
Web translation,
I have experienced many things in other translation projects that I
have to revise again.
However, since the quality of Web translation is also improving,
it should not completely deny it.
It improves translation improvement now.

However, it seems that it has refused participation of a new reviewer
due to the influence which is sticking to quality too much.
Existing members will have a day to change one day.
For that, we must have a new user.
There is no user who can perfectly work perfectly...
It is the same for everything. Both translators and communities...

I am seeing many translations back in English with recent Ubuntu flavors.
It is obviously a lack of reviewer. I hope to solve this problem at an
early date.


Let's continue to provide Ubuntu to Japanese users in good condition.
I will cooperate with it as much as possible.


BALLOON a.k.a. Fu-sen. (Keiichi SHIGA)
balloonakafu...@gmail.com
https://launchpad.net/~balloon

-- 
ubuntu-translators mailing list
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

Re: Japanese team (reviewer) is not working

2017-02-22 Thread Fumihito YOSHIDA 
Hi, I'm Fumihito YOSHIDA, one of admin of Japanese Translators.

  Firstly, thank you for your great contribution to Japanese
translators, and I apologies for my slow reply and your concern.
Probably this reply doesn't enough faster than your expectation, but
not too late for corrections.

  And, I belive that "visibility solve any problem", so I answerd in
this public list. ...Yes, we have limited skill for English
communication, but we (you and me) can try for that.

  Sorry for bothering to other language guys!

  
  Your concern are caused by something our limited resource (include
my lazy) and some imbroglio, I can't divite into strict result, so I
try to expain how Japanese Translator works.
  And, I have one concern about your circs, you send mail to Japanese
Translators admins at 2/21 20:25(JST), but, your first mail in this
list(2/21 21:02 JST) are almost immediately, that have just 30
minutes. So, please share your urgency for that quick actions. I have
half expect, you love *buntu and you are concerned with the lack of
translations in next Z release.
  

  Okay, I try to explain about Ubuntu Japanese Translator system and
contact points, that is part of my answer for your concern.

  Premise: Japanese Translation Team have some contact points and ping
ways.  But we hadn't recieved your contacts. Please use valid way for
that, because we have limited resources in this time.
   Yes, Our IRC meeting habits have are died. Our meeting triggered by
mail in ubuntu-jp lists, sorry for this and not clearly announcement.

  Therefor, this is not real blocker for your translation work. Please
recheck the procedure in our wiki.
  https://wiki.ubuntulinux.jp/Translation

- If you want to contribute japanese translations, you have no call to
below heavy procedure, just do below simplified way.

  0) Input your translation to Rosetta.
  1) Update the waiting list for reviewing. They are coodicate by
per-release rules. If that is not exist, please create new page for
new releases.

  Yes, we are in sometimes busy, from 2015/Oct, that page doesn't work
in now, but we are still in live. Please use this way. This is
combat-proofed/well-trained way in Japanese translations.

- If you want to get translator rights, please use this procedure (at
Japanese wiki).
  see also: https://wiki.ubuntulinux.jp/enroll/translator_candidates

  0) Fill your prereq activities
  1) Update the meeting wiki.
  2) Mail to ubuntu-jp lists for convocation.
  3) Get translator rights, if you have enough credence.

  IMPORTANT NOTE: right of Ubuntu Japanese Translator are not
mandatary for Japanese translations.

  But, I have to say in a straightforward way in this situation with
strong pain, but I say with my sincerity.
  So, Your translation quantities are readlly good (and enough for
reviewing), but that doesn't have enough quality in this moment.
  Please take the suggestions seriously from Ikuya Awashiro before few
years ago.

   I have strong concern about your translation accuracy, so I advice
you that "if you are far from convinced, please stay as English with
braveheart." policy. This is very important part of Japanese
Translators duty.

  
-

  And, I feel desperate need of more explain about our process, please
read below.

  Yet Another Premise: We have 2 explicit (+1 implicit) bars for new
ubuntu japanese translator.

  - Bar 1) Get three endorsement +1 by existence translators. That +1
are provided by review for your past translations.

  - Bar 2) Enough quantities for screening out. Too small quantity
doesn't match process 1).

  - Implicit Bar) You have to prove that you can became good
cooperative guys, that include language skill, ubuntu experiences(as a
user, sometimes administrator in some translations), patience and
humilities for good collaborative activities. This is implicit rule,
but we have CoC, I belived that make sense on fronts!

  Yes, this is heavy process and not low bar, but that have some
historical background.
  In old days, we(Japanese Translators) use open commit policy.  But,
at given day, we met UI crisis by messy commits and license violated
machine translation (e.g.: 「symbolic link -> 象徴的結合」 and using
Excite翻訳) .

  In that days, we have to revert and revert and revert and review and
review and review that many commits, these are really nightmare days
(main worker: Ikuya Awashiro and me).

  After that terrible days, we(+ Japanese Team and Japanese
Translators) have one insight, translation are not easy works
(Especially, you may know, English -> Japanese Translation are!), and
translator must have language skill and good spirit for collaborative
activities. So, we decided to use moderated styles.

  Additionaly, we believe that English(non-translation) are better
than messy translation, becau