ubuntu-manual team mailing list archive

[Ilya Haykinson <haykinson@xxxxxxxxx>]

Hi Matthew,

Thank you for the thoughtful response.

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

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

In our email, we emphasized that the differences are not about our values or
goals, but rather in our _approaches_ to implementing our goals. I would
like to really underscore this again, because I think it's critical to
understanding what made us diverge and what's causing some of today's
collaboration pain.


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

There was certainly some content that was possible to reuse -- as someone
who's written a good chunk of the default applications chapter, I know this
quite well. We were able to reuse (thanks to the compatible license) a lot
of content from the Firefox documentation, and certainly while writing some
other sections I found other parts of the ubuntu-docs work very helpful.

However, a few key things made direct reuse difficult. First, we like to
place things in a lot more context for the user than the task-based docs
provide. Second, there are writing style and voice differences that made
direct reuse (or reuse with minor change) difficult. Third, and really a
far-off last, there was the technical format difference.

Without reliving the previous six months, let's just agree that we may have
been able to share some more content than we ended up doing :-)  Moving
forward, there may be more opportunity for direct reuse. However, let's not
forget that at least for linear and task-based docs, differences in usage
often require differences in writing style and thus make direct reuse
impossible.


> <snip>

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

Our team did benefit from ubuntu-docs's content -- from personal experience,
I know that there were parts of the system I wasn't familiar with and the
system help was quite useful.

I think that because of style differences, the main candidates for reuse
right now and moving forward are the lists of steps. These tend to not
change very much based on writing style, and may be reused in multiple ways
and multiple formats.


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

I think you misunderstood the point Kevin and I were trying to make. We
strongly believe that there should be a single place for the same piece of
content translated into multiple languages (i.e. "localized"). This is
something that has been brought up on the ubuntu-docs side before, and has
been dismissed as something the ubuntu-docs team does not want to do.

Explicitly not taking into account the wants and desires of LoCo teams, I
have a strong belief (mirrored by a large number of people on the
ubuntu-manual team) that a centrally-managed translation of documentation is
something that we want to produce. It does not make sense that an operating
system with the stature of Ubuntu does not have a single set of
documentation available in every language, and accessible in the same manner
and interface regardless of language.


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

We have solved this problem (more or less) with Quickshot. I suggest that
since this tool now exists, hopefully you guys may be able to start using it
for system help :-)


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

I don't think that's likely to happen, as long as the screenshot stays
within the bounds of the help viewer or is clearly identified as a
screenshot. In my view, this should not be a barrier to providing
audio-visual aid to the user. I would also say that screenshots are rather
the simplest type of multimedia that we should be providing -- there are
audio guides (for those with visual impairments), screencasts, etc. I am
glad that our teams are on the same page that these are important.

Perhaps we can break off a discussion on the best way to incorporate
multimedia content into the existing system help, as well as talk about what
kind of multimedia makes sense to shoot for in Maverick, and where it will
live?


> 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 a key problem is the difficulty of contributing to docs. You'll
notice that ubuntu-manual is an open team; ubuntu-docs depends on 17 people
with commit privileges. I would recommend that this may be worth changing on
the docs team to encourage more participation.

However, my main suggestion -- and what we meant in our email -- was that we
need to _radically_ change the ability of the community to contribute. We've
had an open team for months, and made contributing edits and bugs really
simple. Result? A few bugs were submitted via launchpad. We then solicited
bug reports using a web form feeding into a google docs we'd gotten 700
responses over a few days.

What this illustrates is that by making it a one-step automated process for
a casual reader to contribute, and removing as many steps as possible for
other non-core contributors to contribute, we can increase participation and
improve the quality of our output. This is key, and I think is the driving
force behind Benjamin's proposal of the Learning Center site.


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

I would propose the following as an incomplete list of tools that need to be
looked at with a critical eye:

 - tools for creating output in multiple formats
 - investigating alternative translation infrastructures
 - in the context of the Learning Center proposal, tools for contributing in
plain text
 - a better bug reporting tool


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

My point about them looking the same was not that the stylesheet for the
HTML was the same. It was that it really seems like in two years of Ubuntu,
no big change has occurred with regards to documentation. To me, this
implies that the process is too rigid or the focus for docs output is too
narrow.

A website that says it's for "help" should not present the same 15 links in
the same format year after year. It needs to experiment with what works
better; it needs to play with organization approaches. Please review
Benjamin's proposal about the Learning Center -- this is what I would expect
us to want to produce. I think that this is not just a question of how
documents are presented, but a continuous evolution in thinking about the
overall help ecosystem.

I would propose that we agree to consider moving at least the non-community
parts of help.ubuntu.com to the format of the Learning Center or something
similar. It will give us both a chance to rally around designing a new
approach for presenting help content (be it linear tutorial-style content
like the manual, or task-based help like the system help).


> <snip>
> 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 think one step that the ubuntu-docs team could discuss is what it could
change to encourage contributions from the general public. As I've mentioned
before, a lot of this was about producing simple tools (google docs form
took 10 minutes to set up) that allow people to contribute bug reports or
content without a lot of overhead.


> 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 agree with your premise that we should collaborate on one website, but I
would suggest that help.ubuntu.com has not changed in _so_ long that the
more appropriate thing is to look at the overall needs along the lines of
the Learning Center proposal. I think it's a good interface, good proposal,
and even just the design approaches there could help improve usability by
quite a bit.

If you agree, I would prefer to start working on this design as soon as
possible -- there's a lot of dev work there, for sure, even if we simplify
the first release.

-ilya haykinson