Title of guide should be changed to avoid confusion with new installation guide

Wouldn't it make more sense to have *one* installation guide, which has the new "friendly" info at the front, and the more technical info at the back, probably as an appendix or set of appendices?

That way. both newcomers and experienced Linux/Unix people who search online for Ubuntu Installation Guide are likely to find the material they seek. Deciding arbitrarily that "newcomers have priority, so the old guide should give up its name" seems unhelpful.

Jonathan

Thanks for your feedback.

It wouldn't make sense, because then we'd be covering two very different installation methods simultaneously, both ubiquity and debian-installer. We'd also be targeting two very different user groups. When you write (good) documentation, it's very important to write to a specific audience so you can take into account their individual needs and existing knowledge. Writing for non-techs and techs simultaneously will result in something that is unsuitable for both groups. I'm not interested in producing a massive 200 page treatise on everything there is to know about installing Ubuntu either, because *no-one* wants that information. The new guide is being written in response to a perceived user need. Please see https://wiki.ubuntu.com/Specs/KarmicInstallationGuide and https://wiki.ubuntu.com/Specs/KarmicInstallationGuide/FAQs for more on this.

Each guide should link to the other, in order to send users who've accidentally arrived at the wrong guide on to the right one. This bug is about changing the title so that it's immediately obvious which guide is which. I haven't said that the new guide will be called the "Ubuntu Installation Guide". We'll choose a name appropriate to the target audience later on in the development process.

""Deciding arbitrarily that "newcomers have priority, so the old guide should give up its name" seems unhelpful.""

I based the decision on the answers to the following questions: Which is the larger user group? Which user group is more likely to be confused by which guide? Is there a sufficiently large body of legacy users who will be adversely affected by a name change of the installation-guide?

I think there is a set of people who would be well served by a "Beginners Quick Start Guide to Installing Ubuntu", or whatever you will call it. That seems to be roughly what you are aiming for with your new material, having read the Spec and FAQ. That's fine. Inciuding common installation issues that crop up, and how to deal with them, sounds good. 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.

I suspect that determining what the common installation issues for Karmic will be, before it is released, will be a challenge! That set of issues changes from release to release and as different hardware becomes common. The really simple Ubuntu installs in effect need no documentation, they just work; those which do not "just work" need some understanding of what is going on to resolve the issue being encountered. Providing fuller information for the more difficult installation situations, the ones you did not predict ahead of time, would be one logical and appropriate way to help address this.

Statements like "I'm not interested in producing a massive 200 page treatise..." may well be true. 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 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. If the more common use case is browsing on screen, then 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.

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?

(1) Your spec uses the word "comprehensive" to describe itself several times. How is installation documentation comprehensive, if it in fact limits itself to one segment of those installing one variant of Ubuntu on one subset of machines, and to one method among many of doing so? Your own specification mandates comprehensiveness. Please therefore meet that spec, and deliver a comprehensive installation guide.

(2) 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. Anyone who installs Ubuntu (onto a machine they will use themselves) ends up with admin priviledges on that machine (whether desktop, laptop, server, embedded controller, or virtual machine!), and so just became a system administrator of that machine. They may not be an expert (or a "tech", to use your terms) yet, but they are also clearly no longer purely an end user (if they were, some...

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

I'd just like to idly note that, to the best of my recollection (and
apologies if I've missed the odd instance) nobody from the documentation
team has ever once offered to contribute to the existing guide to
improve its structure.

I have no trouble with the assertion that the current guide could be
improved in many ways (although I'd like to see that happen in
conjunction with Debian, who, contrary perhaps to popular belief, have
no overriding reason to want their documentation to be difficult to
understand). I don't actually especially mind changing the title of the
current guide either if we're doing something else, either. I just find
it disappointing that nobody even tried to work with us to improve what
we have.

We see the same with programmers, I guess. It's a lot more fun to write
something new that's all yours. Code isn't documentation but sometimes
the parallels are quite startling. :-)

  http://www.joelonsoftware.com/articles/fog0000000069.html

This seems likely. I'm probably the person from the Doc Team who is most interested in installation, and I've never submitted a patch for it. I can't speak for others, but I've never done this because I'm not interested in the users that this guide is aimed at (and also because contributing upstream like this can be a bit of a hassle sometimes and I'm lazy).

I don't think that the installation-guide is a bad document or that it's impossible to understand, although I understand that my comments may have given that impression. It's just that this document is aimed at a very different, far more advanced, user group to the one that I concentrate on.

It's also worth noting that, if you have some documentation that you want someone to look at, let us (the Doc Team) know! The amount of documentation that ships with Ubuntu is truly immense, and the Doc Team is small and volunteer-led. We can't keep tabs on all of it ourselves, so we really appreciate it when people let us know if something needs particular attention.