ubuntu-manual team mailing list archive

[Kevin Godby <godbyk@xxxxxxxxx>]

Hello, Matthew.

On Tue, May 18, 2010 at 2:10 AM, Matthew East <mdke@xxxxxxxxxx> wrote:
> 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.

I believe both projects share similar goals: producing great
documentation and support for the Ubuntu community.  I don't believe
that we have ideological differences -- only cultural and procedural
differences.  And I think that these differences can be overcome as we
collaborate 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'm very interested in reading those discussions as they may save us
from making the same arguments in the future.  However, I want to
stress that I think we're at a point where we must move beyond
discussions and start taking some action.

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

i think the primary reason that this approach wasn't used is because
the learning curve was too high -- it would've taken too long to get
the toolchain in place to produce the results we wanted.  (All of that
discussion took place before I started the project, so these
statements are based on my own assumptions.)  Since our initial goal
was to produce a printed book and a PDF suitable for printing, the
shortest path from text to book was via LaTeX.  Now that we've
expanded our goals to produce online documentation as well, we're
revisiting our tools and finding them insufficient for the task.
That's why we're now exploring docbook, Mallard, etc.  We try not to
allow the perfect to be the enemy of the good.

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

The first sentence means that if I go to help.ubuntu.com, that
documentation is only available in English. There is no translated
documentation available there, nor any obvious links to find
translated documentation.

> 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 ubuntu-manual team encountered the same problem.  We overcame it
by writing a new application (Quickshot) which allows people to easily
take screenshots in a variety of languages.

I think this highlights one of the cultural differences between our
two projects: Instead of saying, 'Well, that's a difficult problem'
and abandoning the idea entirely, we explore potential solutions to
the problem and work through it.  We've made a conscious decision that
if the current way of doing things (using Rosetta for all
translations, for instance) impedes our progress of achieving our
ultimate goal of great documentation for all Ubuntu users regardless
of language, format, etc., then we'll devise our own procedures and
solutions.

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

Certainly.  I don't think this is an insurmountable problem, however.
It's an issue we need to take into consideration, but it shouldn't
prevent us from including screenshots in the system docs if that will,
in fact, help readers/users.

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

I'm glad to hear this.  Have you done any work yet toward including
screencasts in your documentation?

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

While posting on blogs, microblogs, and websites has helped attract
interest and attention to our project, that alone won't earn you more
contributors.  If those people show up at your website and don't see
an easy way to contribute to your project, they'll move on.  One of
the things we've spent a lot of time working on is making it as easy
as possible for people to contribute in any way they can.  We've tried
to write clear 'how to help us' instructions for each role in our
project.  (We do need to improve these instructions, though, as they
stop a bit short in some cases and need to be more clearly written in
other cases.)  If the ubuntu-doc project wants to attract more
contributes, I think you will need to drastically lower the barrier to
entry.  We're hoping that our proposed project will help with this.

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

The similarity we refer to isn't in the style or color scheme; it
refers to the content of the documentation itself.  While poking
around the documentation for 10.04 LTS, I didn't see any mention of
the Ubuntu-specific features such as the "Me menu" or the "session
indicator".  This documentation may exist, but I didn't notice it.
There appears to be very few differences between the content of the
10.04 LTS docs and the 9.10 docs.

> 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 don't believe that anyone disputes your good intentions.  On the
contrary, I think most people are very grateful for the work that
you've done so far.  But we'd like to start taking it farther and
we're hoping for your help and guidance.

While we can't do much about the lack of time, I'm hoping we can do
something about the lack of volunteers.

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

I agree completely.

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

Have to had a chance to look at our preliminary proposal for the
Ubuntu Support and Learning Center
(https://wiki.ubuntu.com/ubuntu-support-and-learning-center)?

It outlines an idea for a new website that could be reframed as a
replacement for help.ubuntu.com.  I'd love to have your input on our
idea: What aspects of it appeal to you? Which parts do you disagree
with?  Do you think it's a good direction for help.ubuntu.com?

I think we've had a good discussion about our past; now I'd like to
talk about our future.

Thanks!

--Kevin Godby