Feedback request | Documentation site reorg, switch to Markdown

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
31 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
All,

This is a request for feedback from the community.

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 experience for the reader. The
process of building and publishing would also change so that all
projects will use the same method. Not only will this make it easier
compared to current methods but it will allow people to work on
different projects using the same workflow and toolset.

Currently, the "Canonical docs" consist of MAAS, Juju, Ubuntu Core,
and Landscape. There is a central doc site under construction,
docs.ubuntu.com, that would link to all these documentation sites.

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.

All this would entail:

- Initial conversion of all XML files to GFM (GitHub Flavored
Markdown) [1]. Done by Canonical.
- New and actively maintained doc builder [2]
- Streamlined build and publication processes
- A common theme
- Contributions from the Canonical Docs Team members to the current
help.u.c projects (personal time)
- Multiple build formats across the board (where appropriate)

For contributors, workflow changes would be:

- Write in Markdown
- Use a different build tool (local building to verify HTML)

It is my hope that moving to Markdown will act as a catalyst to get
people to contribute to docs again. It is certainly more user-friendly
than the two forms of XML currently in use.

Launchpad and Bazaar will continue to be used for the current help.u.c
topics, mostly due to translations.

Canonical could create a mockup site of the Server Guide to show what
all this would look like, including at the commit, build, and publish
levels.

Note that documentation for the Canonical-sponsored projects is
available for contributions from the community (minus
internationalization at this time) and will be published according to
CC BY-SA 4.0 [3].

Thanks for listening,


--
Peter Matulis,
Documentation
Canonical Ltd.


[1]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
[2]: https://github.com/CanonicalLtd/documentation-builder
[3]: https://creativecommons.org/licenses/by-sa/4.0/

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
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
<[hidden email]> wrote:

> All,
>
> This is a request for feedback from the community.
>
> 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 experience for the reader. The
> process of building and publishing would also change so that all
> projects will use the same method. Not only will this make it easier
> compared to current methods but it will allow people to work on
> different projects using the same workflow and toolset.
>
> Currently, the "Canonical docs" consist of MAAS, Juju, Ubuntu Core,
> and Landscape. There is a central doc site under construction,
> docs.ubuntu.com, that would link to all these documentation sites.
>
> 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.
>
> All this would entail:
>
> - Initial conversion of all XML files to GFM (GitHub Flavored
> Markdown) [1]. Done by Canonical.
> - New and actively maintained doc builder [2]
> - Streamlined build and publication processes
> - A common theme
> - Contributions from the Canonical Docs Team members to the current
> help.u.c projects (personal time)
> - Multiple build formats across the board (where appropriate)
>
> For contributors, workflow changes would be:
>
> - Write in Markdown
> - Use a different build tool (local building to verify HTML)
>
> It is my hope that moving to Markdown will act as a catalyst to get
> people to contribute to docs again. It is certainly more user-friendly
> than the two forms of XML currently in use.
>
> Launchpad and Bazaar will continue to be used for the current help.u.c
> topics, mostly due to translations.
>
> Canonical could create a mockup site of the Server Guide to show what
> all this would look like, including at the commit, build, and publish
> levels.
>
> Note that documentation for the Canonical-sponsored projects is
> available for contributions from the community (minus
> internationalization at this time) and will be published according to
> CC BY-SA 4.0 [3].
>
> Thanks for listening,
>
>
> --
> Peter Matulis,
> Documentation
> Canonical Ltd.
>
>
> [1]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
> [2]: https://github.com/CanonicalLtd/documentation-builder
> [3]: https://creativecommons.org/licenses/by-sa/4.0/

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Chris Perry-2
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 desktop help. Of course I only speak for myself (not for Gunnar
and Doug).

I believe the current desktop help processes work pretty well (though
I'm not saying they couldn't be improved). Peter is proposing to scrap
the existing processes and replace them with new processes that in
terms of inputs (let's describe them as source files in thirty odd
languages) and outputs (let's describe them as html files and packages
in thirty odd languages) do exactly the same thing as the old
processes. But with the new processes all the source files would be in
Markdown.

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 little difference to me whether
it's in Markdown or another markup language. I don't particularly like
any markup language. I'd be able to work faster if we had a
well-designed GUI front-end that hid most of the details of the markup
language.

It's not clear to me that Peter's proposal has significant benefits
for users of the documentation or people who want to contribute to the
documentation. In my opinion Peter has to provide very strong evidence
of significant benefits to get this approved.

Regards,

Chris Perry.



On 15 February 2017 at 22:54, Peter Matulis <[hidden email]> wrote:
> 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
>

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Stephen M. Webb-4
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 little difference to me whether
> it's in Markdown or another markup language. I don't particularly like
> any markup language. I'd be able to work faster if we had a
> well-designed GUI front-end that hid most of the details of the markup
> language.
>
> It's not clear to me that Peter's proposal has significant benefits
> for users of the documentation or people who want to contribute to the
> documentation. In my opinion Peter has to provide very strong evidence
> of significant benefits to get this approved.

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
appear to have something like online documentation.  It's the wrong choice for something like a manual, API docs, or
pretty much anything more than marketing quips or blog comments.

I'm all for a consistent presentation style across Canonical-supported media and across all Ubuntu media.  I don't think
ex-cathedra forcing a workflow and markup switch onto actual writers is the right way to achieve that if you're trying
to encourage participation and quality of content.

So, agreed, I'd like to see a community-friendly discussion on the benefits of moving away from existing workflows and
structure with arguments pro and contra.

--
Stephen M. Webb  <[hidden email]>

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Jeremy Bicha-2
On Thu, Feb 16, 2017 at 8:25 AM, Stephen M. Webb
<[hidden email]> 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
> appear to have something like online documentation.  It's the wrong choice for something like a manual, API docs, or
> pretty much anything more than marketing quips or blog comments.

I'm guessing that the new format will work fine for the Server Guide.

But I'm not sure that it will work as well for the Desktop help which
is a lot more visual and has pictures. For instance, this page:

https://help.ubuntu.com/stable/ubuntu-help/unity-introduction.html
https://help.gnome.org/users/gnome-help/stable/shell-introduction.html

How does your proposal handle that Ubuntu (Unity) currently ships the
Desktop help in the yelp Help viewer which is also used by other GNOME
apps?

I suggest that someone let the GNOME docs team know about this proposal.

Thanks,
Jeremy Bicha

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Gunnar Hjalmarsson
In reply to this post by Peter Matulis-5
[ Replying to the lists I'm subscribed to. Now when the topic has been
announced to multiple lists, I would suggest that the following
discussion is hold on one list, and I suggest ubuntu-doc for the purpose. ]

Hi Peter,

There are three sets of docs at help.ubuntu.com:

* installation guide
* server guide
* desktop guide

Installation guide
------------------
This guide is provided via the installation-guide package, which origins
from Debian, and the published pages are built from that package. It
would make little sense to me to do something else on the Ubuntu side.

Server guide
------------
This guide is currently written in the DocBook XML format, and
translated to a few languages. Others know more about it, so I won't
comment on it further.

Desktop guide
-------------
This guide is currently written in the Mallard XML format. It consists
of about 300 pages which are linked together in an intelligent manner
which provides a reasonable browsing hierarchy. The desktop guide is
translated into 25-30 languages with a decent coverage.

I'm disinclined to support a switch to some other markup language for
these reasons:

1. Mallard serves its purpose well, and the established procedures for
maintaining and publishing the guide work smoothly.

2. GNOME uses it, which gives us a free ride for the maintenance of many
pages which are identical or almost identical. I noticed that both Milo
and Jeremy mentioned this aspect.

3. I fear that a transition to some other markup language, new build
procedures etc. would mean a lot, really a lot of work. Besides the fact
that it's unclear to me who would do it, I fail to see that it would
result in a significantly better documentation or significantly less
work going forward. I simply don't think it would be worth it.


As regards the domain name, it would be doable to move it to
docs.ubuntu.com. It's not apparent to me, though, that the desktop
guide, which targets not-so-tech-savvy end users, would fit so well at
doc.ubuntu.com, which currently is made up of technically advanced stuff
targeting sys admins and package developers. And if we would change the
domain, it's very important that we set up proper redirects from the old
location, so we don't break the many thousand links out there.

"Consistent look and feel" sounds good, and the most important aspect of
that IMO is what the top of the pages look like. We have adapted to the
overall Ubuntu design before, and we can do it again if appropriate
without changing the underlying markup language and build procedures.


So, my gut feeling is that alternative tools should be considered when
starting new sets of docs, for instance the Unity 8 documentation.
Changing tools and procedures for already existing documentation, OTOH,
requires convincing justification. I'm not convinced at this time.

--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Feedback request | Documentation site reorg, switch to Markdown

Doug Smythies
In reply to this post by Chris Perry-2
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 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 content. Plus it lends itself to version control very well.

... Doug
 


--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Chris Perry-2
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 choose to use Markdown for structured
documentation because the advantages (and it has some) would be
outweighed by the disadvantages. For example, one wouldn't choose to
use it for online help (for example, the Ubuntu desktop help).

Regards,

Chris.


On 19 February 2017 at 00:57, Doug Smythies <[hidden email]> wrote:

> 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 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 content. Plus it lends itself to version control very well.
>
> ... Doug
>

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Feedback request | Documentation site reorg, switch to Markdown

Doug Smythies
In reply to this post by Peter Matulis-5
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 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 show what
> all this would look like, including at the commit, build, and publish
> levels.

For years now, you have been trying get agreement to change the
the serverguide to some sort of markdown. I have always wanted to
see a project plan, timeline, and labour estimate. Now you are saying
Canonical would do the initial work (I assume they would want
a project plan, timeline and estimate), so that community concern
is removed.

Would the mentioned mockup site and workflow include translations
workflow? Would it include a PDF mockup serverguide? In my opinion
a PDF serverguide is a must have.

> It is my hope that moving to Markdown will act as a catalyst to get
> people to contribute to docs again. It is certainly more user-friendly
> than the two forms of XML currently in use.

As I have said so many times now, the Serverguide is in
desperate need of subject matter expert help.

Myself, I don't think the change would make any difference to
people's wiliness to contribute. However the feedback
from Robert Young suggests perhaps otherwise.

> Note that documentation for the Canonical-sponsored projects is
> available for contributions from the community (minus
> internationalization at this time) and will be published according to
> CC BY-SA 4.0 [3].

Good.



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
On Sun, Feb 19, 2017 at 2:25 PM, Doug Smythies <[hidden email]> 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 show what
>> all this would look like, including at the commit, build, and publish
>> levels.
>
> For years now, you have been trying get agreement to change the
> the serverguide to some sort of markdown. I have always wanted to
> see a project plan, timeline, and labour estimate. Now you are saying
> Canonical would do the initial work (I assume they would want
> a project plan, timeline and estimate), so that community concern
> is removed.
>
> Would the mentioned mockup site and workflow include translations
> workflow? Would it include a PDF mockup serverguide? In my opinion
> a PDF serverguide is a must have.

Yes, it would include translations.

Yes, it would include a PDF.

>> It is my hope that moving to Markdown will act as a catalyst to get
>> people to contribute to docs again. It is certainly more user-friendly
>> than the two forms of XML currently in use.
>
> As I have said so many times now, the Serverguide is in
> desperate need of subject matter expert help.

Yes, I know. :(

> Myself, I don't think the change would make any difference to
> people's wiliness to contribute. However the feedback
> from Robert Young suggests perhaps otherwise.

The argument about how the GNOME project uses XML is significant.
There was something said about the help facility included on the
desktop image. I'm not sure how that fits in but apparently moving to
Markdown will interfere. I don't understand the statement that
"Markdown doesn't work well with images" but I don't need to know
since there are enough reasons to keep the Desktop on XML.

I believe we still have a chance to revive the Server Guide however.
No, I do not have any scientific proof or psychological studies done
that will guarantee that Markdown will make things better but I don't
think we need to worry since contributions have been so low these last
few years. I'll start the SG mockup project.

As for the Installation Guide, it could benefit from being part of the
family. I'll inquire into the feasibility of converting it.

Apart from workflow and build procedures there is still the question
of appearances. Even if one, two, or all three projects (D, S, IG)
remains as they are there is value (I believe) in herding them
together (theme and URL space). I'll look into the possibility of
doing this.

Any objections?

Peter Matulis

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Chris Perry-2
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 this. If we get the technical reviews then if necessary I
can help Doug do the updates to the server guide, Can't Canonical
provide the technical reviewers? Perhaps I'm misunderstanding
something crucial?

Regards,

Chris.


On 20 February 2017 at 00:38, Peter Matulis <[hidden email]> wrote:

> On Sun, Feb 19, 2017 at 2:25 PM, Doug Smythies <[hidden email]> 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 show what
>>> all this would look like, including at the commit, build, and publish
>>> levels.
>>
>> For years now, you have been trying get agreement to change the
>> the serverguide to some sort of markdown. I have always wanted to
>> see a project plan, timeline, and labour estimate. Now you are saying
>> Canonical would do the initial work (I assume they would want
>> a project plan, timeline and estimate), so that community concern
>> is removed.
>>
>> Would the mentioned mockup site and workflow include translations
>> workflow? Would it include a PDF mockup serverguide? In my opinion
>> a PDF serverguide is a must have.
>
> Yes, it would include translations.
>
> Yes, it would include a PDF.
>
>>> It is my hope that moving to Markdown will act as a catalyst to get
>>> people to contribute to docs again. It is certainly more user-friendly
>>> than the two forms of XML currently in use.
>>
>> As I have said so many times now, the Serverguide is in
>> desperate need of subject matter expert help.
>
> Yes, I know. :(
>
>> Myself, I don't think the change would make any difference to
>> people's wiliness to contribute. However the feedback
>> from Robert Young suggests perhaps otherwise.
>
> The argument about how the GNOME project uses XML is significant.
> There was something said about the help facility included on the
> desktop image. I'm not sure how that fits in but apparently moving to
> Markdown will interfere. I don't understand the statement that
> "Markdown doesn't work well with images" but I don't need to know
> since there are enough reasons to keep the Desktop on XML.
>
> I believe we still have a chance to revive the Server Guide however.
> No, I do not have any scientific proof or psychological studies done
> that will guarantee that Markdown will make things better but I don't
> think we need to worry since contributions have been so low these last
> few years. I'll start the SG mockup project.
>
> As for the Installation Guide, it could benefit from being part of the
> family. I'll inquire into the feasibility of converting it.
>
> Apart from workflow and build procedures there is still the question
> of appearances. Even if one, two, or all three projects (D, S, IG)
> remains as they are there is value (I believe) in herding them
> together (theme and URL space). I'll look into the possibility of
> doing this.
>
> Any objections?
>
> Peter Matulis
>
> --
> ubuntu-doc mailing list
> [hidden email]
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Chris Perry-2
In reply to this post by Peter Matulis-5
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 advantage that I was already set up for bzr,
ssh, and Launchpad and I can see that the requirement to use bzr, ssh,
and Launchpad could put people off - but you're not proposing to
change those I think.

My opinion is that it's too much to ask one-off contributors to go
through the bzr/ssh/Launchpad/xml process or the
bzr/ssh/Launchpad/Markdown process but that anyone who is willing to
do a series of contributions can learn either easily enough. We have
xml for the server guide at present so why expend the effort to switch
to Markdown?

Regards,

Chris.

On 20 February 2017 at 00:38, Peter Matulis <[hidden email]> wrote:

> On Sun, Feb 19, 2017 at 2:25 PM, Doug Smythies <[hidden email]> 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 show what
>>> all this would look like, including at the commit, build, and publish
>>> levels.
>>
>> For years now, you have been trying get agreement to change the
>> the serverguide to some sort of markdown. I have always wanted to
>> see a project plan, timeline, and labour estimate. Now you are saying
>> Canonical would do the initial work (I assume they would want
>> a project plan, timeline and estimate), so that community concern
>> is removed.
>>
>> Would the mentioned mockup site and workflow include translations
>> workflow? Would it include a PDF mockup serverguide? In my opinion
>> a PDF serverguide is a must have.
>
> Yes, it would include translations.
>
> Yes, it would include a PDF.
>
>>> It is my hope that moving to Markdown will act as a catalyst to get
>>> people to contribute to docs again. It is certainly more user-friendly
>>> than the two forms of XML currently in use.
>>
>> As I have said so many times now, the Serverguide is in
>> desperate need of subject matter expert help.
>
> Yes, I know. :(
>
>> Myself, I don't think the change would make any difference to
>> people's wiliness to contribute. However the feedback
>> from Robert Young suggests perhaps otherwise.
>
> The argument about how the GNOME project uses XML is significant.
> There was something said about the help facility included on the
> desktop image. I'm not sure how that fits in but apparently moving to
> Markdown will interfere. I don't understand the statement that
> "Markdown doesn't work well with images" but I don't need to know
> since there are enough reasons to keep the Desktop on XML.
>
> I believe we still have a chance to revive the Server Guide however.
> No, I do not have any scientific proof or psychological studies done
> that will guarantee that Markdown will make things better but I don't
> think we need to worry since contributions have been so low these last
> few years. I'll start the SG mockup project.
>
> As for the Installation Guide, it could benefit from being part of the
> family. I'll inquire into the feasibility of converting it.
>
> Apart from workflow and build procedures there is still the question
> of appearances. Even if one, two, or all three projects (D, S, IG)
> remains as they are there is value (I believe) in herding them
> together (theme and URL space). I'll look into the possibility of
> doing this.
>
> Any objections?
>
> Peter Matulis
>
> --
> ubuntu-doc mailing list
> [hidden email]
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Peter Matulis-5
On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas <[hidden email]>
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 or by Canonical. The idea is
> > that this will provide a better user experience for the reader. The
> > process of building and publishing would also change so that all
> > projects will use the same method. Not only will this make it easier
> > compared to current methods but it will allow people to work on
> > different projects using the same workflow and toolset.
>
> Unfortunately, I do not think it is true that it would be a “better user
> experience for the reader”. I think it would be worse.
>
> > Currently, the "Canonical docs" consist of MAAS, Juju, Ubuntu Core,
> > and Landscape. There is a central doc site under construction,
> > docs.ubuntu.com, that would link to all these documentation sites.
>
> There are two main problems with this approach.
>
> 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 rest of the
> site for each project. The most flagrant example is that docs.ubuntu.com
> pages currently don’t even *link to* the rest of the site for the
> relevant project.
> <https://github.com/ubuntudesign/docs.ubuntu.com/issues/37> Even if that
> was fixed, great effort would be required to implement the rest of the
> navigation, with the same layout, font, etc on
> docs.ubuntu.com pages as on the rest of the project’s site. Compare
> <https://jujucharms.com/> vs. <https://jujucharms.com/docs/> (great!)
> with <https://maas.io/> vs. <http://docs.ubuntu.com/maas/> (woefully
> inconsistent). It would also be much harder to implement a reliable
> search function across any site including its docs.
>

The idea is to improve upon what we have, not to achieve perfection. As you
know, there are pros and cons to any design.

You've outlined some solutions in the GH issue, some of which are easy to
implement and some of which are significantly harder. I don't see anything
insurmountable however. We have a web team looking at this and they happen
to be very good at what they do.

Your first option (your preferred I'm presuming) is to simply integrate
docs into a project's website (a traditional design). This has downsides
too: every doc project would have its own branding, losing the advantage of
a consistent "doc theme" that users will most likely prefer as they jump
from Juju to MAAS to Landscape, technologies that are often used in tandem.
We can always tweak each project's subpage (e.g. docs.ubuntu.com/maas) so
that it retains some "loyalty" to the parent site (e.g. maas.io) all the
while maintaining the foundation of a central theme. I believe I just
described your second option.

In terms of search, your first option gains the ability to scan the rest of
the project's non-docs but you also lose the ability to search across
multiple doc projects which is something we're planning. For the
aforementioned technologies, and soon others, this is a much more powerful
feature IMO.


> Second, scope. While the sites for each of these projects currently have
> a “Docs” section (indeed, Landscape has two), there won’t always be a
> clear distinction between what counts as as “docs” and what does not. A
> simple example is that “Get started with MAAS 2.0”
> <https://maas.io/get-started> is a document, in that it would be
> perfectly useful if you printed it out. But it is also of primary
> importance on the site, and contains minor interactive elements
> (copyable command lines). Similarly you could imagine a walkthrough
> document that starts by prompting you for the name of your package, then
> fills in sample commands including that package name. A single element
> that couldn’t be implemented in Markdown would, apparently, result in
> the document having to be hosted separately from all the others.
>

If we need to write something in HTML in the Markdown files then we can do
so. The parser handles this fine. Fake News!!

(There are minor problems too, mainly involving the ways that browsers
> and search engines would treat docs.ubuntu.com as a separate Web site.)
>

Please elaborate. I'm not a web guy.


> Finally, this statement —
> >…
> > the help wiki, which is not documentation.
> >…
> is bewildering. Of course the help wiki is documentation. It’s an
> unfortunate administrative quirk that help.ubuntu.com has two sets of
> documents, each covering much of the same topics. But moving one set to
> a separate site would make things worse: for example, it would break the
> search.
>

There was some history bundled into my statement. 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 peer reviews and having a
reasonable degree of maintenance applied (the official documentation has
this). One concrete action resulting from this decision was to replace the
header of "Community Documentation" on help.ubuntu.com with "Community Help
Wiki".

It's better that a set of search results points to either reliable
information or unreliable information, not a mix of the two. So it actually
makes sense to separate them, in terms of searching.

I suggest instead finding a way to get the doc builder to generate pages
> that can be inserted into existing project sites, so that they can be
> indexed and navigated in the same way as the rest of the site.
>

This is a reiteration of your option #1 which I acknowledged earlier.

Peter
--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Chris Perry-2
On Mon, Feb 20, 2017 at 5:14 PM, Chris Perry <[hidden email]>
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-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Stephen M. Webb-4
On Thu, Feb 16, 2017 at 8:25 AM, Stephen M. Webb <[hidden email]
> 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
> appear to have something like online documentation.  It's the wrong choice
> for something like a manual, API docs, or
> pretty much anything more than marketing quips or blog comments.
>

Here are two sites I know that use Markdown for technical documentation:

https://jujucharms.com/docs
https://docs.ubuntu.com/maas

Is there something wrong with them?

There is more, however, to consider than visual results. A choice of format
impacts source text readability and ease of use. I am intimately familiar
with both the Ubuntu Server Guide as well as both the above projects and I
can tell you that at least Juju documentation has more non-Canonical
contributors than the Server Guide. This is an important fact, especially
when you consider that Juju is a tiny niche project.

I'm all for a consistent presentation style across Canonical-supported
> media and across all Ubuntu media.  I don't think
> ex-cathedra forcing a workflow and markup switch onto actual writers is
> the right way to achieve that if you're trying
> to encourage participation and quality of content.
>

I don't see any "ex-cathedra forcing" and "markup switch" going on. This
email thread, with the word "feedback request" in its subject and
"proposal" in its second sentence, was sent as far and wide as it possibly
could. There is a lot of discussing going on too.

Peter
--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
In reply to this post by Jeremy Bicha-2
On Thu, Feb 16, 2017 at 8:46 AM, Jeremy Bicha <[hidden email]> 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 will work as well for the Desktop help which
> is a lot more visual and has pictures. For instance, this page:
>
> https://help.ubuntu.com/stable/ubuntu-help/unity-introduction.html
> https://help.gnome.org/users/gnome-help/stable/shell-introduction.html
>
> How does your proposal handle that Ubuntu (Unity) currently ships the
> Desktop help in the yelp Help viewer which is also used by other GNOME
> apps?
>
> I suggest that someone let the GNOME docs team know about this proposal.
>

These are good points that were addressed in another post. I concede that
the Desktop is not a good fit for a change of format.

Peter
--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Tom Davies
Hi :)
Sorry for the long and often off-topic post!

I have not done anything useful in the documentation team for many years
now.  I moved on to other projects.  Even when i was doing stuff i didn't
join in with the team much at all (i'm a bit aspie, i think).

Editing pages helped me learn how to do work on documentation elsewhere,
and how to edit (or update) oddities in Wikipedia.  It was close enough to
html so it was familiar to me and gave me ideas of things to try out.  It
was close to plain-text editing so it helped me gain confidence in editing
config files too and that led me into xml.

I'm not a coder.  I'm definitely into documentation as a way of helping
people migrate away from dependence on restrictive systems and to be less
fearful of trying things that might well suit them better.

I do like the idea of a more consistent look&feel to the documentation,
especially if it makes it look more "professional" and/or friendly.  I
think Ubuntu has done extremely well at that over the years anyway but
mostly by this sort of initiative to pull things together again every so
often.

One good reason (imo) for having different tools for different sorts of
documentation is that it allows people from all sorts of backgrounds to
find a place they do feel comfortable contributing.  Also if one tool
starts to fail then not all is lost.


I thought one of the reasons less people were joining in now was that
permissions to edit some pages has gone wonky a few times in the last
couple of years.

Another reason might be partly my fault :(  I feel really guilty about it
but i value old documentation.  Every time anyone suggests a clean-up to
archive old material i ask the mailing list to make sure that the old stuff
is still available jic it is still relevant to someone out there.  Now that
i have used Arch for a while i do think there is a lot of merit in
decluttering but i still worry about losing people's old edits that might
still be useful.  So, i am a hoarder and feel ashamed that i have always
voted in favour of staying cluttered.

Good luck to all and many thanks from
Tom :)

On 23 February 2017 at 01:26, Peter Matulis <[hidden email]>
wrote:

> On Thu, Feb 16, 2017 at 8:46 AM, Jeremy Bicha <[hidden email]> 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 will work as well for the Desktop help which
> > is a lot more visual and has pictures. For instance, this page:
> >
> > https://help.ubuntu.com/stable/ubuntu-help/unity-introduction.html
> > https://help.gnome.org/users/gnome-help/stable/shell-introduction.html
> >
> > How does your proposal handle that Ubuntu (Unity) currently ships the
> > Desktop help in the yelp Help viewer which is also used by other GNOME
> > apps?
> >
> > I suggest that someone let the GNOME docs team know about this proposal.
> >
>
> These are good points that were addressed in another post. I concede that
> the Desktop is not a good fit for a change of format.
>
> Peter
> --
> ubuntu-doc mailing list
> [hidden email]
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>
--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Matthew Paul Thomas
In reply to this post by Peter Matulis-5
Peter Matulis wrote on 23/02/17 00:03:

>
> On Mon, Feb 20, 2017 at 1:58 PM, Matthew Paul Thomas <[hidden email]
>…
>> 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 rest of
>> the site for each project. The most flagrant example is that
>> docs.ubuntu.com pages currently don’t even *link to* the rest of the
>> site for the relevant project.
>> <https://github.com/ubuntudesign/docs.ubuntu.com/issues/37> Even if
>> that was fixed, great effort would be required to implement the rest
>> of the navigation, with the same layout, font, etc on docs.ubuntu.com
>> pages as on the rest of the project’s site. Compare
>> <https://jujucharms.com/> vs. <https://jujucharms.com/docs/> (great!)
>> with <https://maas.io/> vs. <http://docs.ubuntu.com/maas/> (woefully
>> inconsistent). It would also be much harder to implement a reliable
>> search function across any site including its docs.
>
> 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.

>…
> You've outlined some solutions in the GH issue, some of which are easy
> to implement and some of which are significantly harder. I don't see
> anything insurmountable however. We have a web team looking at this
> and they happen to be very good at what they do.

I know they’re good. I work right next to them. This month I’ve been
working with them. But no matter how good a team is, some things are
much harder than others, some things are naturally prioritized ahead of
others, and some things never get done. You can’t help but remind me of
the bureaucrat who reassures Indiana Jones that “Top Men” are working on
the soon-to-be-forgotten Ark of the Covenant.

As a demonstration, see <https://insights.ubuntu.com/>. Despite the best
of intentions, after four and a half years, the Web team still have not
quite managed to make it consistent with <https://www.ubuntu.com/>. It’s
similar enough that you can tell the differences are accidental, rather
than deliberate: a different logo rendering, a differently styled search
field returning unhelpfully different results (how am I supposed to know
whether the info I want is an “insight” or not?), even an
unintentionally different shade of orange.

That case was more excusable because it was a new site, with a dynamic
CMS, for new materials. Moving existing, static materials to a separate
site is what is so egregious here.

> Your first option (your preferred I'm presuming) is to simply
> integrate docs into a project's website (a traditional design). This
> has downsides too: every doc project would have its own branding,
> losing the advantage of a consistent "doc theme" that users will most
> likely prefer as they jump from Juju to MAAS to Landscape,
> technologies that are often used in tandem.

So we disagree about what’s more important: consistency between
documentation of different products, vs. consistency of a product’s
documentation with the rest of the product’s pages.

I think consistency between documentation of different products is less
important, because the number of interactive elements is tiny. It’s not
as if you’ll click on the wrong button because the buttons are placed
differently in Maas docs than in Landscape docs, or that you’ll fail to
recognize a checkbox because it’s styled differently in the Juju docs
than the Ubuntu Core docs. They contain nary a button or checkbox in the
first place! If we were talking about signup forms, or checkouts, or
video players, that would be a better argument.

And I think consistency between documentation and the rest of the pages
about a product is more important, because (as I said before) while some
things may be definitely “documentation” and some definitely not, other
pages will live in a fuzzy area between the two. Having “Docs” as a
category is a common mistake, but still a mistake — like when a company
categorizes its wares into “Products” and “Solutions”, because they know
which is which, and they haven’t realized that nobody else does.

Even if I’m wrong about all that — even if “Docs” are a clear and
definite thing, and there are people who really really want their Juju
and Ubuntu Core and Maas documents to have a consistent theme — they
could just use readthedocs.org, which would do a far better job than
docs.ubuntu.com simply because it *also* documents thousands of other,
non-Ubuntu-specific projects a developer might be jumping between.

> We can always tweak each project's subpage (e.g.
> docs.ubuntu.com/maas <http://docs.ubuntu.com/maas>) so that it retains
> some "loyalty" to the parent site (e.g. maas.io <http://maas.io>) all
> the while maintaining the foundation of a central theme. I believe I
> just described your second option.
>
> In terms of search, your first option gains the ability to scan the
> rest of the project's non-docs but you also lose the ability to search
> across multiple doc projects which is something we're planning. For
> the aforementioned technologies, and soon others, this is a much more
> powerful feature IMO.

If “soon others” includes Snapcraft, you’ll need to combine search
results from multiple sites anyway (because Snapcraft docs will stay off
docs.ubuntu.com).

>> Second, scope. While the sites for each of these projects currently
>> have a “Docs” section (indeed, Landscape has two), there won’t always
>> be a clear distinction between what counts as as “docs” and what does
>> not. A simple example is that “Get started with MAAS 2.0”
>> <https://maas.io/get-started> is a document, in that it would be
>> perfectly useful if you printed it out. But it is also of primary
>> importance on the site, and contains minor interactive elements
>> (copyable command lines). Similarly you could imagine a walkthrough
>> document that starts by prompting you for the name of your package,
>> then fills in sample commands including that package name. A single
>> element that couldn’t be implemented in Markdown would, apparently,
>> result in the document having to be hosted separately from all the
>> others.
>
> If we need to write something in HTML in the Markdown files then we
> can do so. The parser handles this fine. Fake News!!

The copyable command lines involve an external JavaScript file, so it
wouldn’t be just a matter of inserting HTML — unless you expected and
allowed inlining of scripts into the HTML.

>> (There are minor problems too, mainly involving the ways that
>> browsers and search engines would treat docs.ubuntu.com
>> <http://docs.ubuntu.com> as a separate Web site.)
>
> Please elaborate. I'm not a web guy.

One example is that if you search Google for “Maas”, the relevant search
result includes direct links to the “Get started”, “Tour”, and “How it
works” sections — but not to the “Docs” section, because it is (as far
as Google can tell) on a different site.

A second example is that for any product, if you set your browser’s zoom
level on its docs.ubuntu.com pages, it won’t carry over to the rest of
the site, or vice versa.

A third example is that any UI that arranges pages by site — like
Safari’s tab switcher, or most browsers’ history windows — will assume
that a product’s docs.ubuntu.com pages are a separate site.

As I said, minor problems, but symptoms of the weird IA involved.

>> Finally, this statement —
>> >…
>> > the help wiki, which is not documentation.
>> >…
>> is bewildering. Of course the help wiki is documentation. It’s an
>> unfortunate administrative quirk that help.ubuntu.com has two sets of
>> documents, each covering much of the same topics. But moving one set
>> to a separate site would make things worse: for example, it would
>> break the search.
>
> There was some history bundled into my statement. 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 peer reviews and
> having a reasonable degree of maintenance applied (the official
> documentation has this). One concrete action resulting from this
> decision was to replace the header of "Community Documentation" on
> help.ubuntu.com with "Community Help Wiki".

“Who are you gonna believe, the minutes of a Community Documentation
Team meeting from 2014, or your lying eyes?”

If we’re going to cast into history, I’ll go back further: to July 2006,
when I included “documentation” on a list of words to avoid in anything
produced or overseen by the Documentation Team.
<https://lists.ubuntu.com/archives/ubuntu-doc/2006-July/006669.html>

The reason was that even if software developers see that word as a
meaningful descriptor, end users do not. I can confidently predict that
for end-user help, declaring that some pages are “documentation” — or
even “official documentation” — and that others are not, will not have
altered user behavior one iota.

> It's better that a set of search results points to either reliable
> information or unreliable information, not a mix of the two. So it
> actually makes sense to separate them, in terms of searching.
>…

If it’s really “unreliable”, why host it at all?

--
mpt

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Chris Perry-2
In reply to this post by Peter Matulis-5
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 <[hidden email]> wrote:

> On Mon, Feb 20, 2017 at 5:14 PM, Chris Perry <[hidden email]>
> 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-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request | Documentation site reorg, switch to Markdown

Peter Matulis-5
On Fri, Feb 24, 2017 at 9:11 AM, Douglas Stanley <[hidden email]> 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
> 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.
>
>
Hi Doug, thanks for speaking out, and nice to meet you.

Your idea is interesting. The main problem, though, is the lack of human
resources required. There are only a couple of people who inspect all
incoming contributions, which are, like I said before, primarily reviews
and corrections. So an increase in actual new content in addition to an
extra step of converting to XML is unimaginable.

Peter
--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
12