Feedback request | Documentation site reorg, switch to Markdown

[Gunnar Hjalmarsson]

[ 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