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