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 <jimandma...@gmail.com> 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 _______________________________________________ Mailing list: https://launchpad.net/~ubuntu-manual Post to : ubuntu-manual@lists.launchpad.net Unsubscribe : https://launchpad.net/~ubuntu-manual More help : https://help.launchpad.net/ListHelp
