ubuntu-manual team mailing list archive

[Kevin Godby <godbyk@xxxxxxxxx>]

Hello, Jim.

Thanks for all your help on the manual. Also, thanks for your great
feedback and suggestions.  I've added some more comments below.

On Sat, Apr 27, 2013 at 1:24 PM, Jim Connett <jimandmarcy@xxxxxxxxx> wrote:
> As I am wont to do, I've thought about the positives and negatives of this iteration of the manual. Each manual presents its own surprises and its own unique set of "emergencies". Of course, my desire is that we capitalize on the positives and find ways to learn from the negatives.
>
> Positives
> o Good communication between leads and all involved with regards to due dates and assignments.

This is good to hear. I think good communication is vital to projects like this.

> o Well-developed and tested "help" documents released to aid in installation (tex) and version tracking (bazaar)

Thanks. I'd love to hear more feedback about the style guide and other
documents. Where are they lacking? How can we improve them? What
questions have you or others had that weren't addressed by the
existing documentation?

I have a few ideas for expanding our documentation. I'll work on this
in a couple weeks when I have some more free time.

> o A good foundation for the document has been created, allowing us to reduce our focus on the general information and focus more on the specific changes introduced with each iteration.

I think this is partially true. We should never stop looking at larger
ways to improve our manual, though. Could the content be organized
better?  Could we make instructions and procedures more clear?  Have
we covered common errors and troubleshooting steps?  Have we
documented common questions asked by new Ubuntu users?

> Negatives
> x Not nearly enough authors.

Definitely true. This is something that we struggle with each cycle. I
think we can take steps to improve our outreach/recruiting. We should
also try to discover what reasons folks have for choosing not to join
our project and be an author. Is our authoring process too difficult
to work with? Are they unsure how to get started? Have they just not
considered being an author? What's holding them back?

> x Editing was a challenge this iteration as some authors missed the deadline.

In the future, I think we should try to do a better job of staying on
top of the status of each section/chapter. I'm hoping that the new
\status command will help out a bit here.  (More on this later.)

> x Too many changes in what was finally released in 13.04 that kept us scrambling up to the last second (Gwibber).

Yes, this is always an issue. Unfortunately, it's one that we have
precious little control over.  Each cycle, everyone complains about
the number and lateness of user interface and feature freeze
exceptions (UIFe and FFe).

Ostensibly, these freeze exceptions require the approval of the
documentation team and the translation team. However, approval by Mark
Shuttleworth overrides any nays from the docs and translation teams.

An interesting research project would be to tally up the number of
UIFes and FFes for the past few cycles. Note when the freeze
exceptions were requested, if the docs and translation teams approved
the requests, and if Mark approved the requests.

For the raring cycle, the freeze exception deadlines were moved to try
to avoid having as many exceptions this cycle. It'd be interesting to
know if that had the desired effect.

> x Screenshots seemed to be a bit of an unexpected issue this time around.

I think there was some confusion over who should take screenshots and
when.  I fear I may have contributed to some of this confusion.

My original idea for the screenshot process was that authors would
take draft screenshots. These screenshots would give the official
screenshot team an idea of what the author wanted a screenshot of.
Then the official screenshot team would take all the final
screenshots, ensuring they all had the proper resolution, themes,
usernames, etc.

We're not beholden to this idea, however. We should discuss it and
decide how we'd like to approach screenshots in the future.

> Recommendations
> ! There should be a meeting one week before the due date for authors (and editors if they wish) to gain an assessment of where authors are at in the process...reassign sections if needed, etc. I don't think it works very well to have an authors/editors meeting 1/2 way through the editing process. I think it's better to have these as separate connection points.

Ah, yes. This one is entirely my fault. I meant to have a meeting just
before the first draft deadline to check in with our authors and see
how things were progressing. I got held up with other work and didn't
get a poll sent out in time to establish a meeting time.

Perhaps when we set up the release schedule for saucy we should
establish the meeting schedule at the same time. Then everyone will
know well in advance of when the meetings will take place.

> ! More communication is needed when calls-for-authors and calls-for-editors are made. I remember only seeing one "call" on the 300-or-so RSS feeds I follow. Calls for authors/editors should be done 3-5 times...up to two weeks before the author deadline. In fact, I would even go so far as to recommend we start getting authors/editors lined up now for Saucy.  It appears the Ubuntu Documentation Project is hurting (very badly) for authors/editors, and they've already put the word out for assistance...this means the pool of potential volunteers may become more limited.

Yes, the documentation team is in a bad place right now. I'm going to
try to help them revive the team if I can. I think docs are very
important.

The documentation released for raring is nearly identical to that
released for quantal. The only changes that I'm aware of are a patch
that bumped the version number on the main page from 12.10 to 13.04,
added a couple minor updates to the "What's new?" page, and my patch
that capitalized Dash and Launcher.

I think we're going to try to get a post-release updated pushed out
but we'll see how things go. At the moment, there's only one or two
'active' team members there with commit access to the official bzr
repository.

Benjamin Kerensa created a blueprint to discuss the docs team at UDS
in a couple weeks:
<https://blueprints.launchpad.net/ubuntu/+spec/community-1305-doc-planning>.
 Hopefully we can get things back on track there.

> ! Shave one week off of the author due date and give 3 weeks for editing.  We have all this time to write, but a very narrow window to edit/rewrite as needed.  If our goal now is to always release the new manual with the release of the new version of Ubuntu, I believe editors need just a little more time to do their job.

This is a bit tricky. Currently, the authors' deadline is set to just
a couple days after the feature freeze date.  If we move the deadline
up, then it will be contingent upon the editors to continue to monitor
for added/changed features.

There is a little slack built into the editing deadline. We have a
week set aside for screenshots and indexing and other ancillary
editing work. The editors can generally continue working through that
week without too much problem.

> ! Re-instate the screenshot team. Screenshots should be uniform across the entire manual. Having everyone do their own screenshot...even when using the default theme, tends to produce ever-so-slightly different results. I would estimate it would take two people about 4 hours each at the end of the editing phase to do all the screenshots. (As a side-note...I do not think screenshots should be in the margin! If the concept is important enough to have a screenshot, it should be in the main section of the document.)

I tend to agree with you about the screenshot team. But I'm open to
changing my mind if others disagree strongly. I think the authors
should provide draft screenshots, however, so the screenshot team
doesn't have to try to read the authors' minds based only on a
caption.

The only screenshots that should be placed in the margin are those
that are quite small.  Having a very small screenshot floating in a
pool of white space with a caption inches away looks a bit odd.
Screenshots should never be scaled down to fit in the margin,
however—only cropped.

> So...that's my perspective. take it or leave it.  Again, great job everyone! I'm looking forward to getting started on the next iteration in a few months!

Thanks again for all your feedback and constructive criticism!  I
invite others to provide their own thoughts on what went well this
cycle, what we could do better, and how they think we can improve.

—Kevin