Feedback request | Documentation site reorg, switch to Markdown
Douglas Stanley
doug at dstan.net
Fri Feb 24 14:11:19 UTC 2017
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" <clissold345 at googlemail.com> 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 <peter.matulis at canonical.com>
> wrote:
> > On Mon, Feb 20, 2017 at 5:14 PM, Chris Perry <clissold345 at googlemail.com
> >
> > wrote:
> >
> >> I've never worked on the server guide until today but it was
> >> straightforward for me to set it up, do a simple edit to one of the
> >> xml files
> >
> >
> > Yes, I know it's simple to do a simple edit.
> >
> > Seriously though, I've done a fair amount of writing for the Server Guide
> > myself, but like almost every contributor I've talked to over the years,
> I
> > end up conceding that it's really a PITA to work with. It simply gets in
> the
> > way of writing and, like another past contributor mentioned in this
> thread,
> > you end up with an imposing "ramp-up" wall when one wants to dive back
> in.
> >
> > I have talked to people who have made very significant additions to the
> > guide. These are topics that are complex and extremely valuable to
> capture.
> > Yet they have told me, in no uncertain terms, that they will never do so
> > again, simply because of the XML. These are very bright people, but still
> > they reject the underlying format.
> >
> > <sect8 id="personal rant begins">
> >
> > For the benefit of everyone following along, let's look at an example
> using
> > a "easy" snippet of text from the guide:
> >>
> >> <sect2 id="multipath-config-overview">
> >> <title id="config-overview-title">Configuration File
> >> Overview</title>
> >>
> >> <para>The multipath configuration file is divided into the
> following
> >> sections:</para>
> >>
> >> <variablelist>
> >> <varlistentry>
> >> <term><emphasis role="bold">blacklist</emphasis></term>
> >>
> >> <listitem>
> >> <para>Listing of specific devices that will not be
> considered
> >> for
> >> multipath.</para>
> >> </listitem>
> >> </varlistentry>
> >
> > There are at least 10 "things" here to know in order to do something very
> > simple.
> >
> > Here's something more complex from the same file. I admit that this could
> > have been written in a more orderly fashion but this shows the potential
> > extent of the ugliness awaiting any intrepid traveler:
> >>
> >> <sect2 id="multipath-device-identifiers">
> >> <title>Multipath Device Identifiers</title>
> >>
> >> <para>Each multipath device has a World Wide Identifier (WWID),
> >> which is
> >> guaranteed to be globally unique and unchanging. By default, the
> >> name of
> >> a multipath device is set to its WWID. Alternately, you can set
> the
> >> <emphasis role="bold"><link
> >> linkend="attribute-user_friendly_names">user_friendly_names
> </link>
> >> </emphasis>option in the multipath configuration file, which
> causes
> >> DM-Multipath to use a node-unique alias of the form <emphasis
> >> role="bold">mpathn</emphasis> as the name. For example, a node
> with
> >> two
> >> HBAs attached to a storage controller with two ports via a single
> >> unzoned FC switch sees four devices: <emphasis
> >> role="bold">/dev/sda</emphasis>, <emphasis
> >> role="bold">/dev/sdb</emphasis>, <emphasis
> >> role="bold">/dev/sdc</emphasis>, and <emphasis
> >> role="bold">/dev/sdd</emphasis>. DM-Multipath creates a single
> >> device
> >> with a unique WWID that reroutes I/O to those four underlying
> >> devices
> >> according to the multipath configuration. When the <emphasis
> >> role="bold"><link
> >>
> >> linkend="attribute-user_friendly_names">user_friendly_names<
> /link></emphasis>
> >> configuration option is set to <emphasis
> role="bold">yes</emphasis>,
> >> the
> >> name of the multipath device is set to <emphasis
> >> role="bold">mpathn</emphasis>. When new devices are brought under
> >> the
> >> control of DM-Multipath, the new devices may be seen in two
> >> different
> >> places under the <emphasis role="bold">/dev</emphasis> directory:
> >> <emphasis role="bold">/dev/mapper/mpathn</emphasis> and <emphasis
> >> role="bold">/dev/dm-n</emphasis>. <itemizedlist>
> >> <listitem>
> >> <para>The devices in <emphasis
> >> role="bold">/dev/mapper</emphasis>
> >> are created early in the boot process. Use these devices to
> >> access
> >> the multipathed devices, for example when creating logical
> >> volumes.</para>
> >> </listitem>
> >>
> >> <listitem>
> >> <para>Any devices of the form <emphasis
> >> role="bold">/dev/dm-n</emphasis> are for internal use only
> and
> >> should never be used.</para>
> >> </listitem>
> >> </itemizedlist>For information on the multipath configuration
> >> defaults, including the <emphasis role="bold"><link
> >>
> >> linkend="attribute-user_friendly_names">user_friendly_names<
> /link></emphasis>
> >> configuration option, see Section , <link
> >> linkend="multipath-config-defaults">Configuration File
> >> Defaults</link>. You can also set the name of a multipath device
> to
> >> a
> >> name of your choosing by using the <emphasis role="bold"><link
> >> linkend="attribute-alias">alias</link></emphasis> option in the
> >> <emphasis role="bold">multipaths</emphasis> section of the
> multipath
> >> configuration file. For information on the <emphasis
> >> role="bold">multipaths</emphasis> section of the multipath
> >> configuration
> >> file, see Section, <link
> >> linkend="multipath-config-multipath">Multipaths Device
> Configuration
> >> Attributes</link>.</para>
> >> </sect2>
> >
> > I should mention to the uninitiated that a single wayward character will
> > generate a bewildering error when a build of HTML is attempted.
> Considering
> > that you need to go through a long file full of the above stuff, I
> recall my
> > "debugging" sessions consuming a large amount of my time, not to mention
> the
> > frustration.
> >
> > </sect8>
> >
> >> anyone who is willing to do a series of contributions can learn either
> >> [XML or MD] easily enough. We have
> >> xml for the server guide at present so why expend the effort to switch
> to
> >> Markdown?
> >
> >
> > See above. Also, historically, an extremely high percentage of
> contributions
> > are reviews and corrections. This is easy to achieve with XML precisely
> > because it involves touching the XML very little, if at all. Although
> this
> > type of help is very valuable, what we're discussing here, I hope, is
> how we
> > can get people to actually write new stuff.
> >
> > Is there ANYONE out there that has written a significant amount of
> material
> > for the Server Guide and also believes we should stick with XML/Docbook?
> > These are the people I especially want to hear from.
> >
> > I believe that XML is technically superior to Markdown and it definitely
> has
> > advantages, but only when used in certain contexts. A good example is a
> > single author, or a team of dedicated people, writing for a project,
> like an
> > O'Reilly book, for instance. However, our contributors come and go. Each
> > wants to help but very few will take the time to understand a difficult
> > format unless they expect to do sustained writing. This is just not our
> > reality. What we're trying to solve here is:
> >
> > Find a format that the average person can use to write new material for
> > Ubuntu Server without having to devote an inordinate amount of time
> learning
> > compared to the time they will spend writing.
> >
> > I'd like to say that I am speaking as a community member. Everything I've
> > said above I've believed years ago, before I was a member of the
> Canonical
> > documentation team. At this time, however, the bonus is that there is a
> > chance to improve things at an organizational level as well (explained
> in my
> > initial post). It seems logical therefore to choose a format that the
> other
> > Canonical projects use. We chose Markdown for a reason too (and we *are*
> a
> > dedicated team of people)!
> >
> > Peter
>
> --
> ubuntu-server mailing list
> ubuntu-server at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
> More info: https://wiki.ubuntu.com/ServerTeam
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-server/attachments/20170224/d2911fdd/attachment-0001.html>
More information about the ubuntu-server
mailing list