ubuntu-manual team mailing list archive

[Matthew East <mdke@xxxxxxxxxx>]

Hi Kevin,

On Thu, May 13, 2010 at 9:41 AM, Kevin Godby <godbyk@xxxxxxxxx> wrote:
> On behalf of the Ubuntu Manual team, we wanted to reach out to you to
> start reconciling our two teams' approaches to creating great Ubuntu
> documentation.

Thanks for the positive, thoughtful and constructive email, and sorry
for the delay in responding. I wanted to give you a considered
response and it's been a rather busy week! I should say that what
follows is just my opinion, and others in the team might well disagree
with me on any or all points.

For simplicity I'm going to refer to the Ubuntu Documentation Project
as "ubuntu-doc" and the Ubuntu Manual Project as "ubuntu-manual".

> At the same time, there are some differences in our approaches as well.

I think the critical question for us to consider is whether the
"differences" which you set out below are really differences or not.
In other words, are these fundamental ideological differences which
justify having separate teams and separate processes, or whether they
are merely aspects of ubuntu-doc which could be improved without
forking the project.

Once we've resolved that question, I think that we will have an answer
to the question of whether, and how ubuntu-doc and ubuntu-manual can
work together.

My strong view is that all of the points which you've identified as
"differences" between the projects are simply things which ubuntu-doc
could be doing better and should be thinking about improving. I don't
think there is any single point that ubuntu-doc hasn't discussed in
the past, nor is there anything which is contrary to the team's aims.
And as a result, I feel that ubuntu-doc and ubuntu-manual can and
should definitely collaborate, and ideally should really be working
together as part of the same project.

I'll discuss the specific points you raise below.

> Our team feels that there are some unaddressed gaps in Ubuntu
> documentation. For example, there is a lack of official linear
> documentation -- a guide, hence the UMP project's manual.

As I said quite early on in the last release cycle [1], I can see a
market for a single printable manual. We tend to make a clear
distinction in documentation writing between linear manuals and
onscreen help - they are two very different formats with separate
uses. But both of them have a place in helping users in different
contexts and situations. My problem with the manual team's work hasn't
been their goal of producing a single linear piece of documentation,
but rather it's been the fact that the team has sought to reinvent the
wheel by writing content from scratch, in circumstances where
ubuntu-doc's material was essentially suitable, with modification,
improvement and customisation, to being reused.

[1] https://lists.ubuntu.com/archives/ubuntu-doc/2010-January/014125.html

When the discussion between ubuntu-manual and ubuntu-doc first
started, I showed Benjamin how it was possible using a relatively
small diff and in about an hour's work, to link together the different
articles in the ubuntu-doc bzr branch as chapters of a single docbook
book using a similar structure to the one which ubuntu-manual had
sketched out, and to build it as a pdf file. It needed a fair bit of
work, in terms of improvement to content, writing of new sections, and
improvement of the pdf design, but it was a decent start. I think that
by that stage, ubuntu-manual as a project had already gone down the
route of using different tools (latex rather than docbook), and
Benjamin didn't feel that it was possible to reuse ubuntu-doc content
because of that. However, if things had happened differently, I feel
that ubuntu-manual would have benefitted from ubuntu-doc's existing
material, and ubuntu-doc would also have benefitted from having
improvements to the material made by ubuntu-manual being incorporated
in the original material too.

In summary, I don't think ubuntu-doc has any ideological objection to
a linear manual, it's just that in the past we haven't had the time or
resources to produce one alongside the system help.

> There is
> still a lack of centrally-produced, localized documentation. There is
> very little visual aid in the docs, and no focus on multimedia.

I'm not quite sure what the first sentence here means: obviously our
objective is to produce localised documentation in a central place,
and that's what we do. If it is lacking in certain respects, that's
obviously something that we want to work on.

As to the second sentence, we have discussed many times, most recently
in the past release cycle [2], the use of screenshots in the
documentation. My personal view tends to be that the difficulties of
arranging for translation of the screenshots (because it can't be done
through Rosetta) has meant that using them is undesirable. However, if
a way can be found to facilitate translation of screenshots, then that
may be a way to resolve the problem.

[2] https://wiki.ubuntu.com/MeetingLogs/DocTeam/January2010

The other point we need to be careful of for onscreen help is to
ensure that the user doesn't get visually confused between the
screenshot and the application window that is open. Obviously that
isn't a consideration for a printed manual.

Subject to these points, I don't see any ideological difference
between the teams here.

As to the use of multimedia, we've discussed in the past whether
screencasts could be included in the documentation, and everyone was
pretty keen, as I recall. I believe the team would be keen to discuss
the use of any multimedia that can benefit users.

> We also felt that the Docs Team's process was somewhat rigid, and too
> slow for certain types of contributions. While this approach is very
> consistent with the docs team's emphasis on long-term sustainability
> and quality of the docs process, there was. in our view. much less
> emphasis on widening the scope of documentation and simplifying
> community input.

Lowering the barrier to entry and improving community input is
definitely a key goal of every Ubuntu team, including ubuntu-doc.
While we have made some progress towards (for example) encouraging
people to submit material in plain text, we've clearly not done enough
on this front. I think that ubuntu-manual has shown how to attract
contributors by using a lot of publicity and clear instructions about
how to contribute, and I think this is something that ubuntu-doc could
definitely learn from. I think the major problem is that the team
members frequently don't have much time to promote the team on blogs,
microblogs and websites, and equally sometimes potential new
contributors don't get as much attention and encouragement as they
deserve. ubuntu-manual's enthusiasm could help with that.

So again, I believe that this is not a difference between the teams,
it is just an area where ubuntu-doc has (quite a lot of) scope for
improvement.

> We also felt that there is a place for great tools that could be built
> to help make the process of contributing much easier. This could take
> the form of simplified multimedia content creation (cf. the Quickshot
> tool that we built to simplify capturing screenshots in multiple
> languages); it could take the form of improving our translation
> infrastructure or taking advantage of collaborative editing.

No one could possibly object to the creation of tools that will
facilitate contribution :)

> Finally, and perhaps most acutely, we felt that there is a need to
> create a top-notch documentation system for public help docs that can
> replace the help.ubuntu.com model that's somewhat stagnated since
> Hardy (witness the eerie similarity between
> https://help.ubuntu.com/8.04 and https://help.ubuntu.com/10.04).

Again I think this is an area that ubuntu-doc could look at improving
(and has looked at in the past). The idea of help.ubuntu.com is
(obviously) to be as helpful as possible to users, and any features
that can be added to do that or to facilitate contribution would be
very welcome. Our software is very customisable, and it just requires
people with the right skills and available time to implement features
to improve it. That is particularly true of the help wiki, running
MoinMoin, which is written in python and is easy to theme and to add
plugins/macros. I for one would be delighted if anyone wanted to write
features or improve the theme of the help wiki, or indeed look into
how we could merge help.ubuntu.com (the static part of the site) and
help.ubuntu.com/community (the wiki part) together.

As to the similarity between the two links you've pointed to above,
it's intentional that they look the same - a consistent theme and
presentation is important. When we change the theme to the website, we
rebuild the old pages too with the new theme. But that doesn't mean
that we can't change the theme again, or improve the way that
documents are presented: of course we can and we are open to
discussion about how to do so.

> Now, and most importantly, please understand that we do not mean that
> we need to start from scratch -- we do not seek revolution or
> competition. We do, however, want to achieve our goals, which
> hopefully means that we find a way to coordinate our work rather than
> working independently.

{snip}

> What are your thoughts on this matter? How do you think that we can
> work together? We think that the solution of 'everyone join the
> existing Docs Team process' is not directly workable, since it's clear
> we have some cultural and procedural differences right now -- much as
> having UMP just fork the Docs Team's content is a bad solution. How do
> _you_ think the UMP team can improve the working relationship between
> the two approaches?

I disagree with you that there are cultural and procedural differences
between the teams. As I hope that I've demonstrated above, the things
which you've identified as differences are really just areas where
ubuntu-doc can and should be discussing how improvements can be made.
I think that the way we do things now is born out of good intentions,
and I think that it is a reasonable base for a documentation project,
but I also believe that there is a lot of scope for improvement both
in how we handle contribution and the content that we are producing.
What is stopping us from making those improvements is frequently a
lack of time, and a lack of volunteers. The enthusiasm that
ubuntu-manual has built up could really help with that.

I'm very much in favour of coordination between the teams. And most
fundamentally of all, I believe that it is absolutely imperative that
we provide a single online website where our users can find
documentation. I think that if multiple websites exist, that has two
devastating consequences for users. First - it's confusing because
they don't know where to find material. Second - it's ineffective
because users will find certain answers in one place, and others on
another place. They may even be inconsistent.

So I think that the answer here *is* for us all to work on
improvements to ubuntu-doc's processes, to improve help.ubuntu.com,
and to collaborate on material. Specifically, I think that we could
develop a specification/blueprint around each of the perceived issues
with ubuntu-doc that you've identified above, discuss potential
solutions, and then implement them.

I look forward to your thoughts.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF