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

[Little Girl]

Hey there,

I'm sending my reply again because I forgot to carbon copy it to all
the other lists.

Peter Matulis wrote:

> This is a request for feedback from the community.

I thought I'd chime in on this as a fly on the wall. My vantage point
isn't as a current participator or as an expert participator, but
certainly as someone who has participated in several projects
(including Kubuntu and Ubuntu) in the past and is likely to again.

If the motivation for the change is an attempt to increase
participation, it may not work and isn't likely to be a factor in the
reason(s) for low participation. In my experience, tools aren't
usually the reason people don't participate. Most of us who want to
participate are willing to put up with minor annoyances caused by
tools we don't happen to like or aren't familiar with. Participation
usually drops off for other reasons which should be investigated
independently of the tools used in the project and some of which are
beyond the control of (and unrelated to) the project.

If the motivation for the change is to bring unity to the project,
then that's a solid motivation and one that should be taken
seriously. The project would be strengthened by a "united front"
among all its parts. It would also make it easier for participants to
move from one area to another with little adjustment. All good things.

If Markdown is capable of everything that's currently being done with
Mallard and/or DocBook and/or [insert markup language here], then a
good cheat sheet with conversions from each/any of them to Markdown
would go a long way towards easing the learning curve and making the
adjustment gentle. I see that you linked to a cheat sheet, but a side
by side comparison would be even better.

I seem to remember that there are some seriously tricky things being
done in some of the docs (with the information presented being
dependent on the system viewing it, etc.), so it might be a good idea
to ask for examples of some of the trickier code so that it can be
attempted in Markdown before making the final decision.

Whether Markdown is easier to use or learn than the current tools is
a matter of opinion and will vary from person to person. I,
personally, prefer txt2tags over Markdown, but that could be because
I've used it for several years now and have all kinds of warm fuzzies
for its non-invasive markup (which doesn't affect word counts) and
pretty well unlimited extensibility. At the same time, I can
understand the viewpoint that a markup language that uses words is
more obvious to understand for a newcomer than something that uses
punctuation.

Either way, one of you mentioned that participation is currently at a
low, so it seems that now is a good time to make a change since there
are fewer people who would be affected by it (pleasantly or
otherwise).

My two cents.

-- 
Little Girl

There is no spoon.

-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Robert Young]

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-server mailing list
> ubuntu-server@lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
> More info: https://wiki.ubuntu.com/ServerTeam

-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Alberto Salvia Novella]

Ian Nicholson:

If the ultimate goal is to encourage contributions, I think it would be
more effective to work on offering reasonable tasks to newbies.


(https://en.wikipedia.org/wiki/Muri_(Japanese_term)):
> Muri is a Japanese word meaning "unreasonableness; impossible; beyond
> one's power; too difficult; by force; perforce; forcibly;
> compulsorily; excessiveness; immoderation".
>
> Muri can be avoided through standardized work.


In my experience most tasks are hard only because their processes and 
manuals are overcomplicated. When those are made clear usually working 
becomes trivial.


This means:
- Conversational language, understandable by anyone.
- Details into sub-pages as much as possible.
- Easy to change any time by anyone.
- More screen-shots, less words.
- Covers 90% of common cases, and leaves the rest for asking.

So the idea is designing things to be easy to anybody, instead of 
assuming everyone is an expert. If you observe that's why the Python 
programming language is that successful, for example.





smime.p7s
Description: S/MIME Cryptographic Signature
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Ian Nicholson]

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

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


Speak my name and I appear.

I'll cop to having almost no experience with markdown, so my concerns 
would be:
1 - Are we losing semantic information by switching?  One thing I like 
about the current server guide is that we can do note/warning/info 
sections, will we be able to replicate that with markdown?  Will 
markdown maintain at least equivalent support for a11y tools?  Is a11y 
even relevant when we're talking about authoring documents rather than 
displaying them?
2 - Will we be able to validate that the structure of the document(here 
I'm referring to the formatting) is correct like we do with Docbook?  As 
ugly as the errors are, I never have a doubt whether what I write is 
going to render correctly when I use Docbook.


One thing I noticed about contributing is that when I went looking there 
wasn't a really good xml editor.  I think I ended up using gedit but 
there were some pain points.


Overall though I really like Docbook and I'd hate to see it go. Markdown 
seems like a good language for doing simple display stuff, but Docbook 
is really versatile.
If the ultimate goal is to encourage contributions, I think it would be 
more effective to work on offering reasonable tasks to newbies. At least 
when I started, I was pretty overwhelmed with how much work needed to be 
done; the format of the documentation was the least of my worries.


P.S.  I'm not sure if this will make it through the distribution lists 
due to SPF/DKIM/DMARC, Doug or Peter could you please forward it on if 
it gets caught in spam filters?  Thanks.


--
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-translat...@lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-translators
>
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Alberto Salvia Novella]

Douglas Stanley:
> 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.

Nononono! That's over-engineering!

This is a human problem, not a technical one. What we need is to reach 
consensus, a consensus about what would be the simplest way for most people.


And it seems that every scenario could have a different answer. What I 
do in these cases is to build the same example using various options, 
only then I judge what fits better.






smime.p7s
Description: S/MIME Cryptographic Signature
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Douglas Stanley]

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.

Doug

On Feb 24, 2017 7:24 AM, "Chris Perry"  wrote:

> Hi Peter
>
> Thanks for your reply. I'm slowly getting a better understanding of
> the problem. Your xml quotes are from dm-multipath.xml. The formatting
> in that section seems to me straightforward (sections, a procedure, a
> numbered list, a code example, etc). The markup for a server guide
> table is uglier than your examples I think!
>
> When I'm changing the desktop help I usually change a paragraph, then
> do make and check the html (which takes seconds), so if I've made a
> mistake with the markup and there's a make error message, I know
> roughly where the error must be.
>
> 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).
>
> The server guide is apparently in urgent need of updates, so I'm
> certainly in favour of getting it updated (and I'm willing to help -
> as a technical writer who knows a little about xml but almost nothing
> about server configuration). It's "just" a question of deciding how
> best to do it.
>
> Regards,
>
> Chris.
>
>
> On 23 February 2017 at 00:46, Peter Matulis 
> wrote:
> > 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 form  >>   role="bold">mpathn as the name. For example, a node
> with
> >> two
> >>   

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

[Chris Perry]

Hi Peter

Thanks for your reply. I'm slowly getting a better understanding of
the problem. Your xml quotes are from dm-multipath.xml. The formatting
in that section seems to me straightforward (sections, a procedure, a
numbered list, a code example, etc). The markup for a server guide
table is uglier than your examples I think!

When I'm changing the desktop help I usually change a paragraph, then
do make and check the html (which takes seconds), so if I've made a
mistake with the markup and there's a make error message, I know
roughly where the error must be.

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

The server guide is apparently in urgent need of updates, so I'm
certainly in favour of getting it updated (and I'm willing to help -
as a technical writer who knows a little about xml but almost nothing
about server configuration). It's "just" a question of deciding how
best to do it.

Regards,

Chris.


On 23 February 2017 at 00:46, Peter Matulis  wrote:
> 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 form >   role="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, and >   role="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 the >   role="bold">>
>> linkend="attribute-user_friendly_names">user_friendly_names
>>   configuration option is set to yes,
>> the
>>   name of the multipath device is set to >   role="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 and >   role="bold">/dev/dm-n. 
>>   
>> The devices in > role="bold">/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_frien

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Alberto Salvia Novella]

Peter Matulis:
> 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.

My take:
https://youtu.be/4Bc5lbPHenc




smime.p7s
Description: S/MIME Cryptographic Signature
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Alberto Salvia Novella]

Chris Perry:

"the Serverguide is in desperate need of subject matter expert help".
Your proposal does nothing directly to address this problem.


But it eases other points, so why not considering it?

Most of the time improvement isn't about hitting the bull's eye, but 
rather about doing daily small things. Then the accumulative effect is 
what makes the difference.


For that it's important that people sift from discussing everything in 
advance to pilot scheme, otherwise there will be always fear of getting 
it wrong. People only get convinced by seeing, not by talking.





smime.p7s
Description: S/MIME Cryptographic Signature
-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Chris Perry]

Hi Peter

Yes I object to your proposal to move the server guide to Markdown.

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, generate the html files, and check my change using a
browser. I did have the advantage that I was already set up for bzr,
ssh, and Launchpad and I can see that the requirement to use bzr, ssh,
and Launchpad could put people off - but you're not proposing to
change those I think.

My opinion is that it's too much to ask one-off contributors to go
through the bzr/ssh/Launchpad/xml process or the
bzr/ssh/Launchpad/Markdown process but that anyone who is willing to
do a series of contributions can learn either easily enough. We have
xml for the server guide at present so why expend the effort to switch
to Markdown?

Regards,

Chris.

On 20 February 2017 at 00:38, Peter Matulis  wrote:
> 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-doc mailing list
> ubuntu-...@lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc

-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Chris Perry]

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.


On 20 February 2017 at 00:38, Peter Matulis  wrote:
> 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-doc mailing list
> ubuntu-...@lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc

-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Chris Perry]

Morning all

I wanted to pick up on Stephen's use of the term "semantic
documentation markup". (I'm basically agreeing with some of the points
he made.) Markdown isn't a semantic language, which means that it
knows almost nothing about the structure of the documentation it is
used for. One wouldn't choose to use Markdown for structured
documentation because the advantages (and it has some) would be
outweighed by the disadvantages. For example, one wouldn't choose to
use it for online help (for example, the Ubuntu desktop help).

Regards,

Chris.


On 19 February 2017 at 00:57, Doug Smythies  wrote:
> 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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Robert Young]

Hi all,

As a person interested in contributing for the first time, 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. Just my
two cents.

Robert

On Thu, Feb 16, 2017 at 12:42:52PM +, Chris Perry wrote:
> Hi all
> 
> The volunteer writers working on the desktop help and the server guide
> are Gunnar, Doug, and me. In the interests of transparency I want to
> say that Peter has already discussed his proposal with us (via email).
> I've only worked on the desktop help so I am only qualified to discuss
> the desktop help. Of course I only speak for myself (not for Gunnar
> and Doug).
> 
> I believe the current desktop help processes work pretty well (though
> I'm not saying they couldn't be improved). Peter is proposing to scrap
> the existing processes and replace them with new processes that in
> terms of inputs (let's describe them as source files in thirty odd
> languages) and outputs (let's describe them as html files and packages
> in thirty odd languages) do exactly the same thing as the old
> processes. But with the new processes all the source files would be in
> Markdown.
> 
> 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.
> 
> Regards,
> 
> Chris Perry.
> 
> 
> 
> On 15 February 2017 at 22:54, Peter Matulis  
> wrote:
> > 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
> >
> 
> -- 
> ubuntu-server mailing list
> ubuntu-server@lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
> More info: https://wiki.ubuntu.com/ServerTeam

-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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

[Chris Perry]

Hi all

The volunteer writers working on the desktop help and the server guide
are Gunnar, Doug, and me. In the interests of transparency I want to
say that Peter has already discussed his proposal with us (via email).
I've only worked on the desktop help so I am only qualified to discuss
the desktop help. Of course I only speak for myself (not for Gunnar
and Doug).

I believe the current desktop help processes work pretty well (though
I'm not saying they couldn't be improved). Peter is proposing to scrap
the existing processes and replace them with new processes that in
terms of inputs (let's describe them as source files in thirty odd
languages) and outputs (let's describe them as html files and packages
in thirty odd languages) do exactly the same thing as the old
processes. But with the new processes all the source files would be in
Markdown.

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.

Regards,

Chris Perry.



On 15 February 2017 at 22:54, Peter Matulis  wrote:
> 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
>

-- 
ubuntu-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam

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-server mailing list
ubuntu-server@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
More info: https://wiki.ubuntu.com/ServerTeam