Feedback request | Documentation site reorg, switch to Markdown

[Peter Matulis]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-community-team/attachments/20170222/ba6693f4/attachment-0001.html>