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

[Peter Matulis]

On Fri, Mar 3, 2017 at 11:19 AM, Robert Young 
wrote:

> Hi Simon,
>
> I agree with your assessment. Standard markdown lack some of the
> features that make technical writing easy to read, however, there are
> several extensions to markdown that make it better. Although I really
> like DO's extension, I'm not sure it is a free spec. I know for sure
> that it is not a common spec. On the other hand, Pandoc
> (http://pandoc.org) is a wonderful tool that you can get from the
> standard repos. It has extensions for syntax highlighting, inline html,
> and, most importantly, can convert text from markdown (and dozens of
> other formats) to DocBook and vice versa. I think even if we leave
> DocBook as the official markup choice, Pandoc can be referred to as a
> way for contributors to use the tools they feel most comfortable with,
> but still contribute. I would have to do some testing on the fidelity of
> the format output to what the existing documentation looks like. If this
> is of interest, let me know, and I will start running some tests.
>
>
I'm well aware of pandoc. It's what I used a few years back when I tried to
get the Server Guide converted to RST. It is also the tool that we use in
Canonical to convert stuff. It never converts perfectly. There is always
collateral damage that requires fiddling with. Elsewhere in this thread a
similar idea was proposed: users write in their preferred format and
conversion happens afterwards by a Doc committer. If it's the writer
instead then they are free to do what they want with their time.

I'd also like to mention that in Canonical we do extend the standard GitHub
Markdown.

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

[Doug Smythies]

Hi Robert, Simon,

Both very useful e-mails thanks.

Robert: for unknown reasons (it is not in the held queue)
your e-mails do not get to the docs e-mail list (or the
translators one, I think), so this reply is also to get it there.
Note: e-mails from some others are not getting to all copied lists
either. (See rt.ubuntu.com #29630).

That site you referenced, http://pandoc.org seems like it might
be a useful tool. I do not know the differences between "Markdown"
and "GitHub Flavored Markdown", so don't know if it'll work
on what Peter is proposing. I'll leave it to Peter to reply if
he wants you do some testing or not.

On 2017.03.03 08:20 Robert Young wrote:

> Hi Simon,
>
> I agree with your assessment. Standard markdown lack some of the
> features that make technical writing easy to read, however, there are
> several extensions to markdown that make it better. Although I really
> like DO's extension, I'm not sure it is a free spec. I know for sure
> that it is not a common spec. On the other hand, Pandoc
> (http://pandoc.org) is a wonderful tool that you can get from the
> standard repos. It has extensions for syntax highlighting, inline html,
> and, most importantly, can convert text from markdown (and dozens of
> other formats) to DocBook and vice versa. I think even if we leave
> DocBook as the official markup choice, Pandoc can be referred to as a
> way for contributors to use the tools they feel most comfortable with,
> but still contribute. I would have to do some testing on the fidelity of
> the format output to what the existing documentation looks like. If this
> is of interest, let me know, and I will start running some tests.
>
> Robert
>
> On Fri, Mar 03, 2017 at 12:43:11PM +0200, Simos Xenitellis wrote:
>> On Fri, Feb 24, 2017 at 2:22 PM, Chris Perry  
>> wrote:
>>> Hi Peter
>>>
>> ...
>>>
>>> You used the term PITA (pain in the arse, I think). I (kind of) agree
>>> with what you said about server guide xml being a PITA. All markup
>>> languages are (kind of) a PITA. The problem I have with your proposal
>>> is that (as far as I can see) you're moving from one PITA (server
>>> guide xml) to another PITA (Markdown).
>>>
>> 
>> Digitalocean are using Markdown for their online tutorials.
>> 
>> Compared to the standard markdown
>> (https://guides.github.com/features/mastering-markdown/),
>> they have added some extra features that are suitable for technical
>> documentation.
>> Here is their Writing Guidelines,
>> https://www.digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines
>> which shows off their additions (second-half of the page).
>> 
>> Among the useful features they have added to Markdown (see Writing 
>> Guidelines),
>> 1. Ability to highlight text even in a code environment (for example,
>> in some configuration you can easily highlight the stuff that the user
>> needs to write)
>> 2. Ability to show the command line in five different environment
>> (themes?). If you show commands that you write on Server A, you can
>> specifically use Theme 1 and so on.
>> 3. Ability to show the output of commands in a suitable environment
>> (and also can highlight aspects of that output)
>> 4. Native notes and warnings (in standard markdown, you would need to
>> insert HTML for this)
>> 5. Have the prompt ($ or #) added appropriately because we define that
>> a command line is for superuser or plain user. Also, custom prompts.
>> 
>> There is the Web previewer to try these out at
>> https://www.digitalocean.com/community/markdown
>> 
>> I believe that the standard markdown, as described on github, is not
>> suitable for technical documentation as it lacks features.
>> An enhanced markdown would be more appropriate and more joyful to
>> write documentation.
>> 
>> For me the questions are,
>> a. what "enhanced markdown" can we get that is at least on parity with
>> Docbook XML features.
>> b. is there some tool to autoconvert Docbook XML to markdown?
>> c. will existing core technical writers be happy to switch to markdown?
>> 
>> Simos



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

[Simos Xenitellis]

On Fri, Feb 24, 2017 at 2:22 PM, Chris Perry  wrote:
> Hi Peter
>
...
>
> You used the term PITA (pain in the arse, I think). I (kind of) agree
> with what you said about server guide xml being a PITA. All markup
> languages are (kind of) a PITA. The problem I have with your proposal
> is that (as far as I can see) you're moving from one PITA (server
> guide xml) to another PITA (Markdown).
>

Digitalocean are using Markdown for their online tutorials.

Compared to the standard markdown
(https://guides.github.com/features/mastering-markdown/),
they have added some extra features that are suitable for technical
documentation.
Here is their Writing Guidelines,
https://www.digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines
which shows off their additions (second-half of the page).

Among the useful features they have added to Markdown (see Writing Guidelines),
1. Ability to highlight text even in a code environment (for example,
in some configuration you can easily highlight the stuff that the user
needs to write)
2. Ability to show the command line in five different environment
(themes?). If you show commands that you write on Server A, you can
specifically use Theme 1 and so on.
3. Ability to show the output of commands in a suitable environment
(and also can highlight aspects of that output)
4. Native notes and warnings (in standard markdown, you would need to
insert HTML for this)
5. Have the prompt ($ or #) added appropriately because we define that
a command line is for superuser or plain user. Also, custom prompts.

There is the Web previewer to try these out at
https://www.digitalocean.com/community/markdown

I believe that the standard markdown, as described on github, is not
suitable for technical documentation as it lacks features.
An enhanced markdown would be more appropriate and more joyful to
write documentation.

For me the questions are,
a. what "enhanced markdown" can we get that is at least on parity with
Docbook XML features.
b. is there some tool to autoconvert Docbook XML to markdown?
c. will existing core technical writers be happy to switch to markdown?

Simos

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

[Nathan Haines]

On 02/27/2017 08:00 AM, Doug Smythies wrote:

Very true, and a good point.
Debugging some mistake is very very annoying and time consuming.
In terms of warnings and error messages, I have no experience with the proposed
Markdown method.


Because it's made to look like plain-text, I do have to say that 
debugging Markdown is one of the simplest things there is.  Even GEdit's 
syntax highlighting is sufficient, although there are plenty of of other 
live-preview editors out there as well.



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.


That definitely describes Markdown.  It's the least obtrusive markup 
system I've seen.


--
Nathan Haines
Ubuntu - http://www.ubuntu.com/

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

[Jim Hodapp]

Being part of a team that is now contributing on a weekly basis to
docs.ubuntu.com/core, I can confidently mention that what we are doing with
these contributions has been working out nicely. We have a use case of
needing to contribute high quality documentation that is updated on a
regular basis for our commercial IoT customers. To meet this goal, we've
basically made documentation a required piece for every merge/pull request
for the snaps that we maintain for our commercial customers (obviously
there are a few exceptions where this doesn't make sense). We laid things
out in a tree structure that integrates nicely with documentation-builder,
yet facilitates our team's need to update the documentation rapidly by
being able to peer-review the documentation within our own team. For these
reviews, we are making sure to follow a common style guide. Also of
importance to highlight is that we store the documentation, written in
Markdown, right in each snap's git repository alongside of the code. We've
created a standard directory structure for this and we aggregate this up to
docs.ubuntu.com/core with the use of git-repo. Take a look at the README.md
for how simple this is to work with for generating the final docs [1]. I
can't emphasize enough how easy this structure is to work with and how well
it has scaled for our needs thus far.

It might not be the right model for every use case, but it should be a very
good fit for the majority of use cases surrounding Ubuntu. Markdown is an
absolute pleasure to work with which is a critical point. We developers
generally hate writing documentation and so making it as frictionless as
possible is a very high ideal - one that I think Markdown facilitates quite
nicely.

[1] https://github.com/CanonicalLtd/ubuntu-core-docs/blob/master/README.md

On Mon, Feb 27, 2017 at 11:00 AM, Doug Smythies  wrote:

> On 2017.02.22 16:47 Peter Matulis wrote:
>
> > 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.
>
> Very true, and a good point.
> Debugging some mistake is very very annoying and time consuming.
> In terms of warnings and error messages, I have no experience with the
> proposed
> Markdown method.
>
> > 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.
>
> Either way, I'd still like to hear from Serge Hallyn, Ted Cox, Christian
> Ehrhardt, Nish Aravamudan,
> Simon Quigley, Ian Nicholson.
>
> > 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.
> >
>
> ... Doug
>
>
>
> --
> ubuntu-translators mailing list
> ubuntu-translators@lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
>
-- 
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

[Doug Smythies]

On 2017.02.22 16:47 Peter Matulis wrote:

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

Very true, and a good point.
Debugging some mistake is very very annoying and time consuming.
In terms of warnings and error messages, I have no experience with the proposed
Markdown method.

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

Either way, I'd still like to hear from Serge Hallyn, Ted Cox, Christian 
Ehrhardt, Nish Aravamudan,
Simon Quigley, Ian Nicholson.

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

... Doug



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

[Peter Matulis]

On Fri, Feb 24, 2017 at 7:22 AM, Chris Perry 
wrote:

>
> The problem I have with your proposal
> is that (as far as I can see) you're moving from one PITA (server
> guide xml) to another PITA (Markdown).
>
>
How so?

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

[Peter Matulis]

On Thu, Feb 23, 2017 at 3:03 PM, Matthew Paul Thomas 
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 ) 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.
>
> 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
> >>  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 symp

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

[Peter Matulis]

On Fri, Feb 24, 2017 at 9:11 AM, Douglas Stanley  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
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

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

[Matthew Paul Thomas]

Peter Matulis wrote on 23/02/17 00:03:
> 
> On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas …
>> 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.

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 . Despite the best
of intentions, after four and a half years, the Web team still have not
quite managed to make it consistent with . 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 ) 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'

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

[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

[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

[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

[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: Feedback request | Documentation site reorg, switch to Markdown

[Matthew Paul Thomas]

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

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.

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

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

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

[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


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

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   [cjwat...@ubuntu.com]

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

[Peter Matulis]

On Sun, Feb 19, 2017 at 2:25 PM, Doug Smythies  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
ubuntu-translators@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators

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

[Doug Smythies]

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

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

[Doug Smythies]

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

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

[Gunnar Hjalmarsson]

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

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

[Jeremy Bicha]

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.

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

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

[Stephen M. Webb]

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  

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

[Milo Casagrande]

> On Wed, Feb 15, 2017 at 4:58 PM, Peter Matulis
>  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 

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

[Peter Matulis]

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

Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

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