PDA

View Full Version : Guides to guides



andrew-sayers
June 25th, 2009, 10:31 PM
Over in the Feedback+Help forum, I've suggested (http://ubuntuforums.org/showthread.php?t=1195975) we create a sticky full of "how to follow instructions" guides. These would talk absolute beginners through some of the common tasks involved in following forum instructions - things like pasting commands into a terminal, or saving to a text file. I think this would get a lot of beginners over the initial "what are these magic codes and how do I chant them?" stage. To show what I'm talking about, I've created an example guide (http://ubuntuforums.org/showpost.php?p=7517429) for running terminal commands.

What do you guys all think? If you write your own guides, would you link to instructions like these? What basic instructions would you have liked when you were starting out? Or is the whole idea fatally flawed in some way I don't understand?

- Andrew

starcraft.man
June 25th, 2009, 10:37 PM
Problem 1: Getting people to read stickied guides.

billgoldberg
June 25th, 2009, 10:38 PM
You don't need a guide to guides.

The guide itself should be written clearly so even the most inexperienced users can follow it.

ratcheer
June 25th, 2009, 10:51 PM
What I would like is just a guide that lists and points to all other guides. Like a catalog of guides.

Tim

ajgreeny
June 25th, 2009, 11:19 PM
Try this site, which I used a lot when I first started with Ubuntu 5.04. The guide seems to be updated each time a new version of Ubuntu appears.
http://ubuntuguide.org/wiki/Ubuntu:Jaunty

magmon
June 25th, 2009, 11:32 PM
You don't need a guide to guides.

The guide itself should be written clearly so even the most inexperienced users can follow it.

+1

A guide to reading guides would be nearly as pointless as a book about how to read.

CJ Master
June 25th, 2009, 11:37 PM
Are people really THAT dumb to need a guide on how to read guides...?

andrew-sayers
June 26th, 2009, 01:04 AM
Problem 1: Getting people to read stickied guides.

I agree this is a problem, to some extent. You never see the people that do read stickied guides, because they just lurk quietly, drinking up information.

I propose solving this problem with in-line links, like putting "open a terminal (http://ubuntuforums.org/showpost.php?p=7517429) and do:
...", in individual guides. That would put a link to the solution physically under the eyeball of the reader. Which sort of brings me on to Bill's point:


The guide itself should be written clearly so even the most inexperienced users can follow it.

Again, I agree with this to some extent. But writing out click-by-click instructions every time would be very time-consuming, and would make guides harder to read for everyone else. If you prefer, you can look at a "guide to guides" as a collection of previously-solved problems that writers can use as a labour-saving device. This lets writers get on with the job they're there to do, and still provide very accessible guides.

- Andrew

jenkinbr
June 26th, 2009, 06:12 AM
+1

As a user of guides, when I click the link for a howto, I expect all the info to be right there in the thread, so a new user can print that page, and be happy.

I've personally been peicing together a tutorial that calls for a PDF copy so that users can reverence all the material they need within a simple PDF document. (it's for those who lack an internet connection, if that helps make more sence.(



Bottom line: keep as much info as possible in a single post. Spreading it all over creates clutter and confusion.

monsterstack
June 26th, 2009, 07:06 AM
The howto section of this site is very, very deep. Some sort of categorisation might be nice. You can't always rely on the search feature to find what you want.

andrew-sayers
June 26th, 2009, 12:33 PM
A couple of people have suggested expanding individual guides so that all the necessary information is in one place. Please have a look at the example guide (http://ubuntuforums.org/showpost.php?p=7517429&postcount=5) I wrote up - it's well over a screenful, with several pictures. As a tutorial writer, would you be prepared to include that much information in every guide that included a single terminal command, and to maintain the information across versions?

I understand the desire to have all the information in one place, but if that were a practical solution, tutorial writers would be doing it already.

- Andrew

billgoldberg
June 26th, 2009, 01:01 PM
A couple of people have suggested expanding individual guides so that all the necessary information is in one place. Please have a look at the example guide (http://ubuntuforums.org/showpost.php?p=7517429&postcount=5) I wrote up - it's well over a screenful, with several pictures. As a tutorial writer, would you be prepared to include that much information in every guide that included a single terminal command, and to maintain the information across versions?

I understand the desire to have all the information in one place, but if that were a practical solution, tutorial writers would be doing it already.

- Andrew

That's what I did on those dozens of guides on my blog.

I stopped making them a while back because they get outdated too quickly.

frodon
June 26th, 2009, 01:13 PM
Problem 1: Getting people to read stickied guides.Yep, first thing to know is that almost no one read stickies unfortunately

jenkinbr
June 26th, 2009, 03:35 PM
Yep, first thing to know is that almost no one read stickies unfortunately
I do!

But I'm one out of how many thousand active users?

I also run through the CoC every once in a while - I think even fewer people look at that.

frodon
June 26th, 2009, 03:44 PM
I also run through the CoC every once in a while - I think even fewer people look at that.I wouldn't even try to count them, fortunately most users behave well without reading it :)

Eisenwinter
June 26th, 2009, 03:51 PM
Are people really THAT dumb to need a guide on how to read guides...?
+1. What is this?

jenkinbr
June 26th, 2009, 04:00 PM
I wouldn't even try to count them, fortunately most users behave well without reading it :)
True, that. After all, most of what it has to say boils down to common sence.


1. Be respectful of all users at all times. This means please use etiquette and politeness. Treat people with kindness and gentleness. If you do this the rest of the code of conduct won't need more than a cursory mention.

I'm gonna go back on topic now.

Another problem I see with people placing parts of thier tutorials elsewhere is that it can create a hassle. I really don't see a big deal with typing out how to open a terminal (all they have to do in Ubuntu is go to (Applications >> Accessories >> Terminal) It's not that hard.

When I am responding to support requests, and I need to have a user post the output of a command, the first thing I look at is the username to see if I recognize it from previous interactions. If I don't recognize that, I take a look at the bean count -- If it's over 75 or so, I leave out the instructions on how to open a terminal, as they probably (I don't know for sure) know how to already and don't need the redundancy. If the Bean Count is hidden, I'll go off of the title and bean/mug image (although that method is a bit unreliable as they tend to change from time to time).

andrew-sayers
June 26th, 2009, 06:04 PM
I think we're getting a bit bogged down in the specific issue of a terminal guide, which I just intended as an example of the level of complexity/detail I was thinking of.

In my experience, it's extremely difficult to guess exactly what issues newbies will have. That's partially because every newbie is different, and partially because learning the answers about Linux causes you to forget the questions pretty quickly.

A sticky "how to follow instructions" thread gives users a place to say "please explain what this text means", and an index of answers in the top post gives admins a place to collect all the things that guide-writers need to be clearer about. Even if it's just a one-line summary that's needed, the thread would give us a place to hammer out and index those summaries, and a place for guide-writers to go to find out how to do a better job more quickly.

- Andrew