Quantcast

Feedback request | Documentation site reorg, switch to Markdown

Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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