Ordering of content might need some tweaking

Makes sense to me.

Let's make it happen!

Ok I have rearranged the content in the latex files as per above, and will change the TOC on the wiki page to reflect the new structure.

Currently Chapter 7 is now called "Terminal and System Maintenance" but we can possibly come up with a better title than that. Also jmburgess this affects you as the content you were writing for chapter 6 is now moved to chapter 7.

Jamin

I don't think that this rearranging is enough. If you look at the current TOC structure, we start out with a bunch of very general chapters that really are introductory in nature:

1. An introduction to the manual
2. About Ubuntu in general
3. How to get Ubuntu installed

then we have the one and only chapter on the core use cases:

4. Actually using Ubuntu

followed by a number of more advanced chapters:

5. All sorts of advanced features (customizing)
6. Updating
7. Advanced topics in system maintenance
8. Security

Then we again jump to using the OS:

9. How to use some applications that do not come installed by default

And again we have an advanced chapter:

10. More system maintenance

Note that in all of this, we really have only one chapter (#4) that describes using Ubuntu, and then a bunch of chapters about doing advanced things with Ubuntu, or even with applications not part of Ubuntu by default.

I propose a refinement of the current structure that aligns more with how people may want to use Ubuntu:

1. Introduction (can keep the current chapter)
2. About Ubuntu (can keep the current chapter)
3. Installation (can keep the current chapter, though minus the discussion on non-Desktop versions; these move to ch 15)
4. Understanding your desktop (keep the "Gnome environment" part of the chapter)
5. Getting online (networking, web browsing, email, IM)
6. Using your peripherals (audio, printing, video, multi-mon, etc; talk about managing media within Nautilus too)
7. Controlling your system (Preferences and Administration menus)
8. Using Ubuntu applications (go over each of the default applications and accessories in the Applications menu)
9. Finding and installing more software (Talk about Software Center, touch on synaptic)
10. Keeping your system working well (talk about Update Manager, and any other novice system maintenance tasks)
11. Keeping your system secure (current chapter 8 is probably fine)
12. Advanced topics: Terminal (current "Introduction to the terminal" section of chapter 7)
13. Advanced topics: Useful extra applications (current chapter 9)
14. Advanced topics: Troubleshooting common problems (current chapter 10)
15. Advanced topics: Learning more about Ubuntu (talk about other distros, and how to learn Linux better)

I think that this approach should be a lot more clear, aligned more with how people may want to use their computer, leaves all advanced topics till the end, and in general monotonically increases in complexity rather than jumping around.

Ilya, what you're proposing is a good idea, but it we're talking about a complete reorganization.

How will we find people to cover the extra 5 chapters?

Would it not be better to have Chapter 4 quite a large chapter, with things like "getting online" "using your peripherals" etc as sections in chapter 4, instead of a whole new chapter each?

I'm just trying to keep the overall chapters to a minimum. We don't want users opening the PDF, looking at the Table of Contents and thinking "15 chapters?! I'm never going to get through that many!"

I do agree with you that the chapters need work and refinement.

One of the best things (IMO) that separates Ubuntu from Windows is the flexibility offered by the CLI. I personally wish I knew more about it, but I'm taking the time to do just that. GUI is a good way to break in new users, but we can't push the CLI into the area of "advanced operations." That particular topic should be introduced as soon as possible. Once new users become comfortable with the CLI, they can start experimenting with scripting, etc., as I have in the past year since I started using Ubuntu.

Tacantara,

Yes I hear what you are saying and can see where you are coming from. However remember that we are aiming this manual to be friendly to new people coming fresh from windows/mac or who aren't very tech-savvy. A large number of these people will have absolutely no interest in learning scripting, and who will be put off by using the command line. I do understand that the CLI is extremely powerful and flexible, however many of these people will be thinking "I never had to type anything in windows or mac to do this stuff, why would I want to learn a new OS where I have to type just to get something working?" if we hit them with it right at the start. For those that do want to learn more about scripting and CLI etc, there are boundless resources available for them to access - I just don't think that is the point of this manual.

I don't want to open a can of worms here about the whole CLI vs GUI debate as this isn't the place, and I know lots of people have strong opinions on this. I guess the question is, should being comfortable with the CLI be a pre-requisite for someone to learn and become comfortable using Ubuntu effectively? Surely there is a place in linux/ubuntu for the average joe's wife that just wants to know how to install the operating system, surf the net, chat to people, and watch videos etc, and I think Ubuntu has progressed to a point now where this can largely be done sans-CLI.

Anyway that's where I see the first part of this manual heading, with a gentle introduction to the CLI later on.

Benjamin - I agree that sticking with 10 chapters is a good idea, so it stays user-friendly, light and accessible. Perhaps we can incorporate some of Ilya's ideas into the existing 10 chapters as you suggested?

@Benjamin,

I am not really tied to the number of chapters. For example, Chapter 1 and Chapter 2 are not really long enough to be "chapters" in their own right, and can be considered more of a Prologue. There's also a way to reorganize my proposed set into fewer chapters, such as for example:

Prologue and About Ubuntu (current chapters 1 and 2)
1. Installation (can keep the current chapter, though minus the discussion on non-Desktop versions; these move to ch 15)
2. Understanding your desktop (keep the "Gnome environment" part of the chapter)
3. Getting online (networking, web browsing, email, IM)
4. Using your peripherals (audio, printing, video, multi-mon, etc; talk about managing media within Nautilus too)
5. Controlling your system (Preferences and Administration menus, discussion on security)
6. Using Ubuntu applications (go over each of the default applications and accessories in the Applications menu)
7. Finding and installing more software (Talk about Software Center, touch on synaptic)
8. Keeping your system working well (talk about Update Manager, and any other novice system maintenance tasks)
9. Advanced topics: Terminal, Troubleshooting common problems (current "Introduction to the terminal" section of chapter 7, current chapter 10)
10. Advanced topics: Learning more about Ubuntu, Other applications (talk about other distros, and how to learn Linux better; current chapter 9)

So here's a way to cut this down to short prologue + 10 chapters. An in-depth discussion of the CLI can go with troubleshooting in chapter 9, and other apps can live under "learning more" in chapter 10.

As far as content, I think that we may want to rethink task allocation and make it sub-chapter (i.e. have second-level headings assignable), which will allow us to work on the final structure and will allow more people to collaborate.

However, I do think that the current structure focuses entirely too much on topics that assume that the user does not have Ubuntu at all (current chapters 1, 2, and 3), or has Ubuntu working well and wants to do more with it (chapters 5 - 10). Philosophically, if we're aiming at new users -- new computer users, new Ubuntu users -- we need to do a kick-ass job on the core "using Ubuntu" use case, and can leave the really advanced or ancillary use cases mainly to the documentation team.

@tacantra, I too like the fact that contemporary GUI-based operating systems, Ubuntu included, often have powerful command prompts. However, I think that -- much like JaminDay wrote -- having the CLI featured heavily in a beginners manual is going to be counter-productive to helping new users feel comfortable that they can use Ubuntu instead of Windows/Mac OS. This does not, however, prevent us from including some CLI stuff in asides clearly marked as advanced use, even earlier in the book than the last few chapters.

What Ilya has described despite being perhaps a little hard work is definitely worth it. It makes the project appear to be much more of a professional layout and definitely helps break down the learning stages for an Ubuntu Novice. Ilya's reform gets a +1 from me.

I agree while 5 extra chapters is too much for now, keeping it at 10 chapters but re-ordering it is an excellent idea. Although if this is to be done it must be done before alpha release.
+1
Ryan Macnish

> Date: Sat, 9 Jan 2010 06:00:07 +0000
> From: <email address hidden>
> To: <email address hidden>
> Subject: [Ubuntu-manual] [Bug 504668] Re: Ordering of content might need some tweaking
>
> What Ilya has described despite being perhaps a little hard work is
> definitely worth it. It makes the project appear to be much more of a
> professional layout and definitely helps break down the learning stages
> for an Ubuntu Novice. Ilya's reform gets a +1 from me.
>
> --
> Ordering of content might need some tweaking
> https://bugs.launchpad.net/bugs/504668
> You received this bug notification because you are a member of Ubuntu
> Manual Team, which is a bug assignee.
>
> Status in Ubuntu Manual: Confirmed
>
> Bug description:
> I have been taking a look at our current TOC and am wondering whether it needs to be tweaked slightly. My concern is that we will be asking users to open a terminal and type commands within the first six chapters, however it is not until chapter 7 that we have an 'introduction to the terminal' that explains what it is and what sudo means etc. This doesn't make sense to me and could be confusing/offputting to a beginner.
>
> My suggestion is this:
>
> 1. Rename chapter 6 to simply "Updates and Upgrades", and remove the section on "system maintenance".
> 2. Rename chapter 7 to "System Maintenance", and make the content on system maintenance (that was in chapter 6) a new subsection of chapter 7, following the 'introduction to the terminal' subsection.
>
> That way, I think we could almost get away with not using the command line at all for the entire first part of the manual, as it's mostly gui-based stuff. Then when the reader gets to part II - advanced, the first thing they read is an introduction to the terminal.
>
> Hope that all made sense. Anyone have any other suggestions?
>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~ubuntu-manual
> Post to : <email address hidden>
> Unsubscribe : https://launchpad.net/~ubuntu-manual
> More help : https://help.launchpad.net/ListHelp

_________________________________________________________________
View photos of singles in your area! Browse profiles for FREE
http://clk.atdmt.com/NMN/go/150855801/direct/01/

The terminal really is a place where only people are really into linux go. The idea of splitting up the book into the two sections is very smart and what is required so that we can give a user a quick overview of everything, keeping in mind that they don't care about a lot of advanced topics. For many people, their Ubuntu box is a media player that does internet stuff, and I think that really is the crowd we are aiming at.

I think Ilya's ch 1-5 make sense, but chapter 6 might be a little crazy. Going over EVERY item in the applications list is crazy, it should be more like selected applications, that are installed by default. I have figure out how to do such commands as sudo apt-get clean from the GUI (using computer janitor) and I also think we need to include backup in the maintenance section. There are plenty of GUI options, and we just need to choose one and roll with it. I propose TimeVault to be used for that.

Now the key is we need to contact all of the current writers of the chapters, and tell them about the new chapter changes (assuming we go through with them) which at this point and time, might be a little hard, but not ridiculous. Because of all the extra media attention we have received, we have the people and some of these chapters seem to be created such that multiple people can work on the same chapter.

My vote is to go for it.

Ok, here is piece of thought.

I do think we have to re-organize the manual. I think Ilya is proposing an interesting arrangement, but that Benjamin also has a point in keeping the number of chapters low. But I don't think we should do it because people might not want to read the manual as a whole, because (or at least as far as I know) that is not the point of the manual. I think of it more as a reference guide.

I think we should separate the really essential parts of using ubuntu, and write them down to a manual.

0. Introduction to the manual
---
1. Introduction to Ubuntu
2. Installing Ubuntu (because the user already knows what ubuntu is, so if user likes it, user should install, else close the book and go use a not-so-nice OS)
3. Making yourself at home (to understand ubuntu, and how to get along with it)
4. Making home yours (how to customize your desktop, and install new applications and stuff.. Make your computer yours)
5. Giving your system maintenance
---
6. Getting to the core (introduces the user the under-the-hood section, and why should the user know about it)
7. The terminal is your friend (explains how to understand/use terminals)
---
8. For common problems, common solutions (sort of like troubleshooting part I guess. I think the terminal part needs to be before this one, as this one most likely will require use of terminals).

I know that my organization is not the best one, but I just wanted to do this before I went to sleep. I think that I have made my point in that we have to group similar things to a further level to make this manual more user friendly. Please don't complain about my chapter names or numbering, that can obviously be changed ;), I just wanted descriptive titles to help me write less stuff inside the parentheses

I like Ilya's second proposal, but Joe is right - we don't need to go through every single application that's in the default install.

I don't like how our whole advanced section is condensed into two chapters though. We need to combine some of the middle stuff and then have it balance out, maybe something like 7:3 or 6:4.

Perhaps:

Prologue and About Ubuntu
1. Installation
2. Introduction to the Gnome desktop
3. Internet, Emails and IM
4. Settings and external devices
5. Software and Packaging
6. System Maintenance
7. Using the Terminal
8. Troubleshooting common problems
10. Learning more about Linux and Extra Applications

Ch 1 & 2 => prologue

Ch 3 => Ch 1
Anthing on which version, goes to Ch. 10

Gnome part of Ch. 4 => Ch 2
Plus stuff on nautilus

Ch.3 Titled Applications contains
Rhytmbox
F-Spot
OpenOffice
Tomboy
Empathy
Firefox
Evolution
Totem
ubuntu one

Include a note on restricted extras when it first comes up

Ch. 4 Settings (Pretty much key parts in the system menu)
Setting up Printers
changing Users
Configuring Desktop Effects
Configure appearance (themes)
Configure screensaver/wallpaper
Display

Ch. 5 is just the applications section of old ch. 4 expanded a bit

Ch. 6 is pretty much old ch 6 without the cleaning up packages bit (there is no proper gui for it) and also will include backup (with TimeVault)

Ch 7 is the introduction to the terminal part of old ch. 7.

Ch 8 is old ch 10

Ch 9 Learning more about Linux and Extra Applications is new chapter on learning more and getting more help. It also includes choosing a version, and talks about the other derivatives of Ubuntu. It will also have the extra apps list (no detail, just list and link)
Cheese
The GIMP
Gnome Do
Google Chrome
Jokosher Audio Editor
Pitivi
Sun Virtualbox
VLC
Wine

^^

This is what Joe Burgess, Thomas Cantera and I came up with in the meeting on Saturday. See the logs for more detail.

Basically we think we've got a Table of Contents that covers everything we presently have, and some more. It's not too long, it's not too confusing and it gets harder as it advances.

Thoughts from everyone please?

I would suggest that we *not* even have a chapter on the terminal [chapter 7]. Defer it to the advanced section , where it would serve as an introduction to the terminal usage.

For a few reasons:
- There is a profound fear among new users that Linux==terminal knowledge is a must. Not mentioning the terminal or giving it importance in the simple guide will ease the user's fear a bit.
- Since it is just an intro to the terminal , something which we dont want a user to use. Why introduce it?
As mentioning it here makes it seem it is something the user needs to know about.
- One of the desktop goals is to purge sudo from the desktop >
https://blueprints.launchpad.net/ubuntu/+spec/security-karmic-no-sudo

Also to note: pitivi is planned to be in the default install. Is it justified to have it in chapter 9 ?

Scratch that: after a recent Update Pitivi is *already* included in Lucid by default . So it will be in Alpha 2.

Vish: The advanced section is basically going to be from Chapter 7 onwards, so technically the terminal stuff is in the advanced section. Yeah I forgot Pitivi was on the default install, this is just a mistake. It won't be in our final extra apps list.

I think the new structure is good, and seems to progress in an intuitive way. Ie starting with an explanation of the installation process, to navigating your new system and it's default layout/software, to slowly learning how to configure and set it up to the way you want, add more programs, and then get into more advanced stuff.

My only comment would be is that the old chapter 7 - introduction to the terminal - had some advanced stuff in it, even for an 'advanced' section of a beginners manual. Will a beginner really need to know how to use virtual terminals? Even manipulating files (which can be done GUI quite effectively) might be unnecessary. Just a thought but I think keeping it simple would be ideal.

At the end of the day, we could probably throw around ideas regarding tweaks to the structure for weeks. Sure it's important to get it right, but at some stage we need to settle on it and move on, or we will never get content written in time! Good work guys and +1 from me.

--JaminDay

+1 from me. I think the new plan will work as a good introduction.

Perhaps, like JaminDay says, we can do something about Chapter 7 not being a pure introduction to the terminal, but perhaps a task-oriented one? What if we merge chapter 7 and 8 and just create a "troubleshooting" chapter, which starts off covering the CLI (since that's a pretty common starting point for troubleshooting things).

- Vish is right when he says "There is a profound fear among new users that Linux==terminal knowledge is a must. Not mentioning the terminal or giving it importance in the simple guide will ease the user's fear a bit."
I think the more you get used to Ubuntu the more you like the CLI, beginners will discover it, each one at his/her own pace.

- We don't need to go through every single application that's in the default install. Right!!! and if we have to mention extra applications they have to be found in the "Ubuntu Software Center" - easy-to-install-apps, by the way nobody is mentioning Ubuntu One.

- For the rest I buy Ilya's second proposal

Agreed

*
*
2010/1/10 Martin Kaba <email address hidden>

> - Vish is right when he says "There is a profound fear among new users
> that Linux==terminal knowledge is a must. Not mentioning the terminal or
> giving it importance in the simple guide will ease the user's fear a bit."
> I think the more you get used to Ubuntu the more you like the CLI,
> beginners will discover it, each one at his/her own pace.
>
> - We don't need to go through every single application that's in the
> default install. Right!!! and if we have to mention extra applications
> they have to be found in the "Ubuntu Software Center" - easy-to-install-
> apps, by the way nobody is mentioning Ubuntu One.
>
> - For the rest I buy Ilya's second proposal
>
> --
> Ordering of content might need some tweaking
> https://bugs.launchpad.net/bugs/504668
> You received this bug notification because you are a member of Ubuntu
> Manual Team, which is a bug assignee.
>
> Status in Ubuntu Manual: In Progress
>
> Bug description:
> I have been taking a look at our current TOC and am wondering whether it
> needs to be tweaked slightly. My concern is that we will be asking users to
> open a terminal and type commands within the first six chapters, however it
> is not until chapter 7 that we have an 'introduction to the terminal' that
> explains what it is and what sudo means etc. This doesn't make sense to me
> and could be confusing/offputting to a beginner.
>
> My suggestion is this:
>
> 1. Rename chapter 6 to simply "Updates and Upgrades", and remove the
> section on "system maintenance".
> 2. Rename chapter 7 to "System Maintenance", and make the content on system
> maintenance (that was in chapter 6) a new subsection of chapter 7, following
> the 'introduction to the terminal' subsection.
>
> That way, I think we could almost get away with not using the command line
> at all for the entire first part of the manual, as it's mostly gui-based
> stuff. Then when the reader gets to part II - advanced, the first thing they
> read is an introduction to the terminal.
>
> Hope that all made sense. Anyone have any other suggestions?
>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~ubuntu-manual<https://launchpad.net/%7Eubuntu-manual>
> Post to : <email address hidden>
> Unsubscribe : https://launchpad.net/~ubuntu-manual<https://launchpad.net/%7Eubuntu-manual>
> More help : https://help.launchpad.net/ListHelp
>

Okay I'm going to start changing over the blueprints and wiki to the new ToC.

New table of contents up on the wiki: https://wiki.ubuntu.com/ubuntu-manual/TableOfContents

Wiki page ToC and blueprints now all reflect the new Table of Contents.

Just waiting on Joe to update the LaTeX stuff.