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 partic
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 extensi
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
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
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
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
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
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 w
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 f
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"
> sess
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 ne
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
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 we
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
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 go
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 ugli
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 re
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 w
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
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
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 pe
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
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 s
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 expe
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 adv
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 d
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
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 s
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
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
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
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
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 c
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 deskt
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 litt
> 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
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 C
37 matches
Mail list logo
