An appeal for Plain English!

[MZ250Supa5]

Over my relatively short time as an Ubuntu user, (around two years now) I've received much help and encouragement from fellow users, and on occasion have seen some very well written How-To guides that assume absolutely no prior knowledge, and have left felt empowered. But all too often I've found guides to be frustratingly difficult to follow, and this has left me feeling angered as well as frustrated - often only to find on further enquiry that a simple, all important step has been left out of the guide, sometimes by oversight, but all too often because it appeared to be an 'obvious' step by the guide writer, so they left it out assuming that anyone would know. In my years as both a learner and a teacher I've learnt that the only thing anyone can afford to assume, is to assume nothing.

Any 'simple' guide should be just that, assuming absolutely no prior knowledge, and explaining every step, even to the point of almost insulting those who have progressed beyond the basic position of having no knowledge at all. Beginners do need their hands holding a lot, and their learning benefits from having a lot of repetition, as that is how most of us actually learn things. Granted, once we become 'fluent' we easily forget how we learned, and in retrospect it becomes difficult to empathise with the frustrations of the learner who is a complete beginner.

I also can empathise with the experienced Linux user who is altruistic enough to spend time helping out people new to the OS, but if that leaves someone lost and frustrated and facing the unsympathetic comments by some of our community when they ask for further elucidation, usually of the nature that perhaps they should go back to using Windows doesn't help,especially if all that it would take would be an easy to understand and follow guide that has been tested on a willing guinea pig, (i.e. the least techie person you know). If it works for them, then it's a fair guess that it will work for others, and as a result will build our community.

I'm not naturally a very techie person, but I am an enthusiastic user of Ubuntu, and am quite evangelical and have managed to gain quite a few converts, which sometimes leaves me in the invidious position of being the first stop for technical advice - not that I mind in the least, but I do sometimes find it very annoying when I can't get my head around a supposedly simple guide because the well intentioned writer has not placed themselves in the position of their intended audience. This is largely a matter of decent editing by someone who can write, but who also has sufficient technical confidence to try out instructions and then ask when they get stuck.

It used to be said that the definition of competence was the ability to pass on information about a process in a way that others will readily understand, and whilst I'm sure that this is true for advanced tutorials and geek to geek communication, this does not often appear to be the case with many guides supposedly aimed at newcomers.

None of the above is intended to upset anyone, and I am trying to be constructive, and as a positive move, I am prepared to be a guinea pig for those of you who wish to write tutorials and How-To guides. It's always easier to deal with people who already have a fair amount of knowledge and understanding, but it is equally hard to deal with those who lack the knowledge and understanding, but who can only progress if they learn the language.

So, there is the challenge, please send me your tutorials and How-To guides, for me to test, but please, be prepared for lots of questions, as I shall be adopting an 'idiot' stance. I will rewrite where I feel necessary and send it back to you for your approval.

We were all beginners at one stage, and though many in our community are 'naturally' more techie than others, I see no reason why Mr or Ms average should not become at least competent in getting their system to do what they want with the minimum of frustrations without hightailing it back to Windows territory.

[Sean Moran]

I agree, that it is important to keep the foundations of the audience in mind before ecpecting to be understood, and can only suggest also, that as well as clear guidelines for every step along the procedural way, that some take for-granted, that a few screenshots with little red numbered arrows can paint a thousand words too.

[Red_Steve]

I wish there was a way to give your more credit for this true statement than just saying: +1!

[cipherboy_loc]

I wish there was a way to give your more credit for this true statement than just saying: +1!

Same here. Way to go MZ250Supa5.



Cipherboy

[grahammechanical]

Wow! An appeal for plain English from a Welsh person. You write just like me and I am a cockney. I like to use good language and I also see the need to explain things from the beginning. That way I understand what I am talking about. My disappointment is that the guides do not explain what you need to look for when they suggest you run this or that code in a terminal. Nor, do they explain how having that information helps to diagnose the problem.

I guess that as this is a community that is based on the premise of use what we give and then get involved yourself, we have to get involved making the improvements we desire. What we come up with will be just as good as anybody else's efforts. If there are technical errors then others in the community will let us know. Better still let them correct what is wrong.

Regards.

[apoth]

There's plenty of guides on the wiki (and plenty of holes in them). Follow some, if you have problems post here and if you find the answers, fill in the holes?

[matthew.ball]

Excellent post. I understand exactly what you mean. It's been a few years for me and I've become slightly used to the expectations/assumptions in some guides, but occasionally I find myself off guard.

Just slightly off-topic... Is there a place on UF where tutorials are "requested" so-to-speak? Something like "I would like to read a tutorial about X".

I'm pretty interested in writing some tutorials, but I don't think many people on UF would actually be interested in the tools I play around with. If however there was a post which asked for a tutorial on something I know, I would give it a shot in an instant.

[drs305]

I agree with the OP.

I would add that any user that doesn't understand something in a tutorial should not be afraid to contact the author to point out areas that need clarification or expansion. Posts have "edit" buttons!

If one person doesn't understand it then there are lots of others that don't either but are too timid to ask. The guides won't be improved until someone speaks up. Communication can be within the thread (I don't understand X, would you please explain...) or via PM (at least for me).
;-)

Added:
Of course, it depends on the audience. My "Grub2 - 5 Basic Tasks" should be simple for a novice to understand. Conversely, when I direct someone to the "Title Tweaks" thread I provide a "geek alert" warning and expect the user to have a bit more understanding...

[aytech]

Probly everyone had these problems. I once followed the ubuntu guide to install wicd network manager. In the guide the commands I had to enter looked like this:


sudo apt-get remove network-manager
sudo reboot
sudo apt-get install wicd

Guess what happened after I uninstalled the network manager and restarted :D

[cpmman]

I have considerable sympathy with the op's intent. Unfortunately it is almost unavoidable to use jargon in any discipline. Whilst changing the oil on your beloved Muzzi may be simple to describe in a way that non-mechanics can understand it is a different matter when it comes to describing how to perform a de-coke. The same applies here except that the target audience is world-wide and disparate in both hardware and software ownership and knowledge. Taking post #2's point white space is essential to guides at the risk of lengthening perceived readability.

[Oxwivi]

If one person doesn't understand it then there are lots of others that don't either but are too timid to ask. The guides won't be improved until someone speaks up. Communication can be within the thread (I don't understand X, would you please explain...) or via PM (at least for me).
;-)
Wikis, for example, have multiple authors, and there's no one obvious to contact about it. And the reader won't be able to understand and improve the guide. The roots of the problem should be addressed: guide writers are obligated to write assuming no knowledge, I agree with OP.

[Bodsda]

I find myself in two minds about the OP.

Whilst I agree that steps should not be missed from a guide, I disagree that the guide should be extended to the point of allowing my dog to follow it (not calling anyone a dog here).

Research is required on the part of the reader as well as the writer.

I recently started looking at HomeBrew for my wii. The wiki page for this is no where near a step by step guide and is rather confusing, but after doing some research and understanding what the writers were trying to achieve, it becomes easier to follow.

If every guide had to explain in depth what a terminal is before they started getting on with the point of the post, then we would end up with an extreme amount of long winded pointless pages of tutorials that would further annoy anyone with basic knowledge.

Take the packaging guide on the wiki for example, if you know nothing about debian packaging/programming/development steps/CLI/compiling then chances are you cant work your way through that guide. That does not mean that the guide is of poor quality, or unfinished, it is simply that it does what all decent documents do, they aim at a specific audience; which for guides is usually someone with some prior knowledge but not in depth.

Another good example, is the Electricity page on wikipedia. I went looking for some info there when I was putting three phase power into our server room at work and after 5 minutes on the page I put my tail back between my legs and ran. This was not because the page was not good, but because it was explaining Electricity and all the complicated mathamatics that go with it, which was not what I was after.

In short, if you are the intended audience of a guide, you should be able to follow it, otherwise it is a poor guide.

Bodsda

[Oxwivi]

Yes, while guides should be just that, a guide, it should not try to explain each and everything. If it needs to be explained, the terms could be linked to their respective explanatory pages.

Should we write a guide to write guides?

[grief -l]

I do sometimes find it very annoying when I can't get my head around a supposedly simple guide because the well intentioned writer has not placed themselves in the position of their intended audience. This is largely a matter of decent editing by someone who can write.

Possibly because you have ignored the tuxtosterone phenomenon, where said writer addresses a certain audience but his intended audience is in actual fact those who will supposedly be wowed by the unix wizardry being presented. Any "decent editing by someone who can write" would defeat the object of the exercise.

[pbpersson]

Volunteering to become the editor for all Ubuntu articles for everyone on the planet sounds like a daunting task.

I have been in IT since 1983 and have concluded that usually the more knowledgeable one is in the inner workings of the computer, the worse they are at explaining their knowledge.

This is not always the case but it is quite often true. They also become rather miffed when asked to explain how to perform simple tasks we were all expected to know the moment we left the womb, such as how to grant permissions and privileges to files from the terminal prompt. ;)

[forrestcupp]

The OP needs to get a simpler name. :)

[cpmman]

The OP needs to get a simpler name. :)

It is simple if you are a motorbike fan. That was my point - jargon is endemic in all disciplines.

[irv]

I have been in IT since 1983 and have concluded that usually the more knowledgeable one is in the inner workings of the computer, the worse they are at explaining their knowledge.
I agree with the above quote. I am retired from a IT position, and thought because I was knowledgeable about computers I was qualified to teach a class at the local high school. I found out this was not true because I talk above the class because I used terms they didn't understand. I had to bring this down to, "this is a mouse", "this is a keyboard"

On the subject of the OP, there is a right way to do how to's. Even on wiki site, there is a "How to Write a How to Article" at, http://www.wikihow.com/Write-a-How-to-Article (http://www.wikihow.com/Write-a-How-to-Article), and I believe there is some guide lines on how to do a "howto" on the Ubuntu forum also. I think I read something a few years ago so I am not 100% sure of that.

Nice discussion here.

[cracker89]

Wow! An appeal for plain English from a Welsh person. You write just like me and I am a cockney. I like to use good language and I also see the need to explain things from the beginning. That way I understand what I am talking about. My disappointment is that the guides do not explain what you need to look for when they suggest you run this or that code in a terminal. Nor, do they explain how having that information helps to diagnose the problem.

I guess that as this is a community that is based on the premise of use what we give and then get involved yourself, we have to get involved making the improvements we desire. What we come up with will be just as good as anybody else's efforts. If there are technical errors then others in the community will let us know. Better still let them correct what is wrong.

Regards.

Aye. That makes a lot of sense. You want to contribute, but theres only so much that you know. And there's all that there is to learn. Just like torrents. So in addition to English, please seed your downloads too. :) Cheerios.

©ommunity, not ©orporations.

[scouser73]

I totally agree with the op about this.

[cracker89]

Probly everyone had these problems. I once followed the ubuntu guide to install wicd network manager. In the guide the commands I had to enter looked like this:


sudo apt-get remove network-manager
sudo reboot
sudo apt-get install wicd
Guess what happened after I uninstalled the network manager and restarted :D
Lawl... classic man

[Windows Nerd]

I disagree with the OP. There is jargon associated with each and every profession. If someone is writing a tutorial, they often have a specific target audience. If the tutorial is how to do something very complicated and requires a great deal of explanation of how to do it and it is very hard to do right, the writer is obviously going to assume some basic knowledge or pre-requisites. It would take the author of such tutorial way to much time to explain how to do those basic things, and could possibly result in the tutorial being too long, and not to the point. It also makes any tutorial harder to follow when you have to sort out the information intended to explain basics you already know: if you skip over this stuff to save some time reading a long tutorial, there is some likelihood of you accidentally skipping over the important stuff.

It's not that all tutorials need to be confusing and hard to follow. It's just that some will be intended for more advanced users and are written with them in mind.

It's just like learning, say, to be a physicist. A person without calculus (a basic skill in Physics) would be utterly lost if he or she is going through a lesson, and the instructor is not just going to stop the class and explain how calculus works and spend a class (or more. since with calculus, the instructor could spend a year just explaining all the calculus concepts) going over it rather than teaching what everyone else would like to learn about or know.

It's the same with tech how-to's and tutorials. A person writing a how-to on building a web/LAMP/mail/etc server for an enterprise (which is a very advanced process, and is difficult sometimes for even experienced IT admins) is not going to stop and say "ok, this is a terminal" or "this is the super-user, it can do anything you ask it to and assumes you know what you are doing". Unless the book is specifically targeted towards someone who does not know those concepts, the book will assume it.

I do understand your request for simplified tutorials, and sometimes a tutorial may be a bit confusingly written. Geeks are not always very sociable or great at communicating ideas. If you have a question about a tutorial, feel free to contact the author. More than likely they will be happy to help you. It is up to you to ask to clarify a point, not the author. The author is already doing you a favor by writing said tutorial/how-to. You have to take the initiative.

Scott

[wilee-nilee]

I agree that things should be clear. But It is important to have the tools for the task. This description by the OP is based on no cause and effect evidence, such as a actual wrongly written anything.

If you don't understand it find someone who does or study it until you do or give up on it. This appeal seems rational but to be honest makes no sense to me.