Hi Kevin, On Thu, May 13, 2010 at 9:41 AM, Kevin Godby <god...@gmail.com> 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 _______________________________________________ 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
