Hi Jonathan,

Wow, that's a long post. I apologise in advance for the necessary length of my reply. Also, please understand that I'm replying on behalf of a team of 7 people here, not just myself.

I think it might help if I first give you some background on my desire to create a new installation guide. I've been a member of the Ubuntu Documentation team for several years now, and the first work that I performed there was writing the Switching from Windows guide. This is now in need of replacement. My assessment of the state of that guide was that it tried to be all things to all people, and ended up failing to be useful to anyone. (You may have noticed that I'm worried about something similar happening here!) There were no defined user personas, no general aim to the guide, etc., fairly vital ingredients to producing good documentation. You can't just say that "this document is for everyone!"; you have to have a clear picture of who you're writing for in your head at all times.

While thinking about how best to replace the SFW guide, I tried to identify the needs of users by analysing IRC logs (about 2GB worth of questions!) and looking at the most popular pages on the help wiki and the forums. My findings surprised me (always a good sign that I'm not making things up); it seemed that *lots* of people were interested in relatively basic installation-related questions. For example, the most popular page on the help wiki, even more popular than the front page, is a document on how to burn Ubuntu to an ISO. That puts us firmly in non-technical user territory. A technical user, in my definition, would most likely understand the concept of CD images, or at least know what to do with them. My proposed solution was to write an official installation guide aimed at these users. How many users have we lost over the years because they couldn't figure-out a "simple" thing like burning an ISO, I wonder?

I was aware of the installation-guide package and have skimmed through it previously. It is *completely* unsuitable for non-technical users. I know this from experience. I previously worked in technical support, have worked as a technical reviewer on a book ("Ubuntu for Non-Geeks"), and have been writing documentation for a good 4-5 years now. Still, you shouldn't have to take my word for it. Print a copy of the guide out and find a non-technical user and see what they understand. See if they can install Ubuntu, without any prompting from you. My expectation is that most would fall at the first hurdle and fail to burn the ISO onto a CD correctly!

OK, so hopefully that's enough background. I'll now move on to addressing some specific points from your reply. Forgive me if I sound a little terse, I'm trying to be brief.

(a) "Putting some more technical material along with that introductory material should help ensure that all the material related to Ubuntu installation is clear and consistent in its use of terminology, and so would make both parts of the whole more useful."

When we write documentation, we refer to a style guide. This ensures consistent terminology. Consistency is a poor reason to include technical information. A good reason to include technical information is if it is necessary to allow the user to accomplish their task.

(b) "determining what the common installation issues for Karmic will be, before it is released, will be a challenge!"

Indeed, which is why Nathan Handler is filling a role entirely devoted to user testing and collecting information on common problems. My own researches suggest that there are certain issues which crop-up every release, such as GRUB errors and problems with partitioning. We will concentrate on these as much as possible, since handling hardware-specific problems is too big a task, as you say. It is likely that only hardware-specific problems with sufficiently common hardware will be included in the Troubleshooting section.

(c) "The really simple Ubuntu installs in effect need no documentation"

It seems likely from this comment that you have never seen an unassisted non-technical user install Ubuntu for themselves. You may be surprised at the problems people run into. Besides, ubiquity isn't the biggest generator of user assistance queries. It's the bits before, and possibly after, that are.

(d) "That does not mean what you personally are or are not interested in is the best way to decide what the Ubuntu community as a whole is best served by"

I hope I have answered this comment by explaining my motivations, above. I am basing as many of my decisions as possible on user testing and analysis of common user assistance queries. My interests lie firmly in providing a good user experience for our users, although I understand that perhaps that wasn't obvious.

(e) ""I don't think many "non-tech" end users will be printing out this installation documentation anyway, so number of pages is perhaps a poor metric to be using.""

That's true, but I do anticipate a use case where people hand out the guide along with an Ubuntu CD. It remains to be seen whether this is a significant use case, but I believe it could be an important one from a marketing perspective.

The fact that the document is not necessarily for printing does not mean that we should just jam as much material into it as possible (N.B. pages are a convenient measurement of the size of a document). Big documents are daunting, take longer to download and are more difficult to maintain. Translators may not translate them, since it would take such a lot of effort which could be better spent elsewhere. Users may feel swamped by the many different choices of information that they are presented with.

In addition, there are certain topics which would overlap, but which would have to be covered in very different ways depending on the user. System requirements are a good example. A technical user may want to know if Ubuntu runs on the IA-64 architecture. They probably just want to quickly look at a simple table. A non-technical user doesn't have a clue what "architecture" means in this context, and they shouldn't have to. Should we explain it to them to convince them that they don't need to understand this information, that it's for advanced users only? They just want to know if Ubuntu runs on "their" computer, whatever "architecture" that may be. This overlap would be a severe problem if, as you propose, the existing guide is extended with new material aimed at the users I'm interested in.

(f) "...a good table of contents and a carefully written introduction will ensure that those who only need to read the first two chapters (or whatever it is) will not somehow (accidentally?) waste time reading the later more detailed material they do not require."

That's a very hopeful picture of how users work! You're more likely to find that users will see a massive TOC, scan for words related to the problem they're trying to solve and click them. If they see "Installing Ubuntu blah blah Windows", they will click on it, even if that topic is some horrendous "Installing Ubuntu while retaining the Windows bootloader". Users (including you!) typically have short attention spans when they're looking at documentation, and will probably give up looking after a couple of tries, especially if the only material they've found seems to be too complicated anyway.

(g) "Am I really the first and only person in the Ubuntu user community to ever suggest that it would be more appropriate for you to work *with* the existing documentation, combining it (perhaps in updated/revised form) with your proposed new material, rather than insisting that it rename itself for you?"

No, others have voiced concerns, and I welcome the criticism. However, it's important to understand that generalising things doesn't always make sense, as I have endeavoured to explain. From my perspective (and by extension, the Ubuntu Doc team's), working with the existing document will result in a guide which is difficult to maintain and which would require a *lot* of rewriting to be made even remotely suitable. I have explained above why I think that creating a combined guide would not be in the users' best interests. I hope you also see that the needs of non-technical and technical users overlap very little in this case, in terms of the information that they're looking for and what they're trying to achieve.

My insistence to rename the installation-guide, assuming that both guides exist simultaneously, is borne out of pragmatism. See my previous comment.

(h) ""Your spec uses the word "comprehensive" to describe itself several times""

Yes, you're right. I wrote that spec a few months ago, but I think I was trying to use "comprehensive" to describe a guide which covers the whole of the installation process in question, start to finish, and not every type of installation process. I apologise for putting it in such misleading terms, and will change the wording.

(i) ""You speak of "two very different user groups", yet in reality there is no clear "bright line" test separating these two groups, that I know of.""

I'm talking about two user groups all the time because it's convenient. I know the reality is more complicated. However, there are archetypal users which characterise the user groups that I'm thinking of, and I'm thinking about just a few of these representative archetypes in each of my groups. I suppose that it's unhelpful that I haven't written down these archetypes (we will have better non-technical user personas on the spec soon, though). Understand this: Just because someone is anointed a "system administrator" by default when they install an OS doesn't automatically give them the knowledge and motivations that are typical of the user group that I'm calling "system administrators". They are not techs. They are still, in terms of knowledge/motivations, and end-user/non-tech. There is a big difference in skill levels. It is possible to sort most people into one of the two broad groups.

(j) "if they were, someone else, the system admin, would have done the operating system install on their behalf, or they would have purchased a machine with Ubuntu pre-installed!"

No, no, no! That's the problem we're trying to fix! Ubuntu is easy enough for these people to install, we're just trying to enable them by providing good help and support, and to remove the hurdles that are blocking them!

(k) "There is a wide spectrum of users, each with unique backgrounds, who wish to install Ubuntu."

There *is* a wide spectrum of users, but that spectrum isn't uniformly populated. There are some parts of the spectrum with far more users than others! I'm concentrating on a part which I believe to contain a *very* large number of users. It's not everyone, but it's enough people to make a big difference if I can improve their user experience. Your example of the guy installing Ubuntu on a 486 or something is a much smaller user group. I'd like to help out that guy eventually, but I'd rather do the most good for the most people first of all. There aren't enough hours in the day to help everyone at once.

(l) "Desktop or laptop users may in time discover the delights of virtual machines...there is no clear and obvious way to decide up front exactly what a particular user will need to know"

Do you think that they will have the guide pinned open for a period of several months, just in case they suddenly gain an interest in some other task that relates to installation? They will have forgotten about the guide by then, and will just go and look for something appropriate, wherever/whatever that may be. That may be the current installation-guide, which will still be there, just with a more appropriate name! I'm not suggesting that we delete it!

(m) "Please join the existing work in the general area you are interested in, improve and add to that work, rather than railing against it as not being quite what you are personally "interested in producing" and so striking out on your own -- much less also demanding that the existing documentation rename itself to get out of your way!"

See above. I am not scratching an itch, and I'm not some newbie who's dreamed this up in the shower. I've been thinking about this sort of thing for *years*. Indeed, I've been working on it for years, within the Ubuntu community, no less! I asked for the existing document to be renamed for practical reasons, which I have outlined. I ask that you respect my request.

(n) "Please develop updated installation documentation as a logically consistent, comprehensive and integrated whole, and please do not require that existing installation documentation rename itself so you can focus exclusively on one part of the user community at the expense of another."

I hope that my justifications above are satisfactory to you, and make this final request of yours redundant. I await any further comments.