<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Mon, Feb 20, 2017 at 5:14 PM, Chris Perry <<a href="mailto:clissold345@googlemail.com" target="_blank">clissold345@googlemail.com</a>> wrote:</div><div class="gmail_quote"> <blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> 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 </blockquote><div> </div><div>Yes, I know it's simple to do a simple edit.</div><div> </div><div>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.</div><div> </div><div>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.</div><div> </div><div><sect8 id="personal rant begins"></div><div> </div><div>For the benefit of everyone following along, let's look at an example using a "easy" snippet of text from the guide:</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><pre style="font-family:"ubuntubeta mono","ubuntu mono",monospace;color:rgb(0,0,0);font-size:12.8697px"> <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></pre></blockquote><div>There are at least 10 "things" here to know in order to do something very simple. </div><div> </div><div>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:</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><pre style="font-family:"ubuntubeta mono","ubuntu mono",monospace;color:rgb(0,0,0);font-size:12.8697px"> <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></pre></blockquote><div>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. </div><div> </div><div></sect8> </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">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?</blockquote><div> </div><div>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.</div><div> </div><div>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.</div><div> </div><div><div>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:</div><div> </div><div>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.</div></div><div> </div><div>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)! </div><div> </div><div>Peter</div></div></div></div>