View Full Version : Ubuntu Needs More Plain English

March 30th, 2008, 03:15 AM
I have been using Linux for quite a while and I must say that I am familiar with the jargon. It's just that, I think that Ubuntu can be understood easier if there was more plain English.

I stumbled upon this post (http://www.fsckin.com/2008/03/28/ubuntu-hardy-heron-804-release-notes-rewritten-in-plain-english/) that tells about Hardy's release notes in plain English. I must say that it was very easy to understand even if I am familiar with the jargon.

I don't have an idea on how this kind of "plain English" is to be put on ubuntu.com but I just want to share about it anyway. After all, Ubuntu is supposed to be Linux for human beings.

March 30th, 2008, 03:30 AM
That link is more persuasive than informative. The release notes at http://www.ubuntu.com/testing/hardy/beta are aimed at people who want to test the beta version of Hardy, so it's not unreasonable to expect a little understanding of Ubuntu.

Good, understandable documentation is often hard to come by for near enough anything technical.

March 30th, 2008, 03:35 AM
The new sound system is fantastic! Now you can play movies, music, and voice chat at the same time without running into problems.

I could do this before....

I think the direction you're trying to go with the release notes is a good one. I think you still need some polish on presenting the message, though.

March 30th, 2008, 03:36 AM
I would rather accurate information, than simplified.

Technical subjects unsurprisingly have technical descriptions.

Mr. Picklesworth
March 30th, 2008, 04:26 AM
this post (http://www.fsckin.com/2008/03/28/ubuntu-hardy-heron-804-release-notes-rewritten-in-plain-english/) that tells about Hardy's release notes in plain English

That is an example of a horribly misleading and clumsy "plain English" explanation and precisely what we should never want. Many things that were suggested in the real release notes as new possibilities are listed as features. Those features do not actually exist, but these notes actually list them as being there. The world clock is not a new program, but a change to an existing program. (BIG difference). Inkscape is not included by default, has been in the repos for a while, and is not aimed directly at that use case. It is best not to make people think that. (Rather, it now can fit that use case, which is notable).
By not calling programs by their actual name or purpose (eg: Inkscape is never mentioned, "the remote control" application could be anything), those softened release notes are impossible to follow by example; people would look for the magical features and get lost.
Same flaw with "downloading large files". What the heck does that mean?! Transmission has nothing whatsoever to do with downloading large files. Rather, a torrent file could be anything from 5 kilobytes to a thousand gigabytes, but no matter what is a very special kind of file. Transmission doesn't just magically appear when somebody wants to download something.
Small error: Used "wizard-based program" to describe Brasero. "What is a wizard?"
One more thing: Encouraging misinformation is bad. I am convinced that people calling their web browser "the Internet" was brought on by nasty strategies from certain monopolistic corporations to ensure that people stick with their trademark "Internet" browser out of unawareness of there being anything better (since all other groups stick with the proper language). This "internet browser"... it opens web pages and is used to browse the web... notice any inconsistencies there? Having said that, a program capable of viewing every type of information sent over the Internet would be pretty interesting.

Don't get me wrong, easier release notes are nice (eg: Link to definitions of things like xorg, explain stuff quickly where necessary), but they have to maintain some meaning. That particular example looks like shady marketting speak for a product that needs to sound better than it is, which is easily achieved by vaguely mentioning features but not where they are or how they work.

The simplification here sounds like it is for monkeys learning English, which is maybe a bit too far to the other end of the spectrum. There is a sweet spot somewhere in the middle that does not insult anyone's intelligence, but provides information useful and interesting to all. Accuracy is important here, to avoid misrepresenting details of the release. If that very important accuracy sounds a tad technical, then so be it; at least we don't have a list of fixed bugs with their summaries beside them (a practise which does nothing but confuse the unaware).
On the good side, I think the frequent use of screenshots to demonstrate features, with such a high text to shot ratio (yet keeping them small and unobtrusive) would work perfectly to do that, even coupled with the current release notes' text.

I hope you can forgive me for that rather inflamatory first paragraph. In fairness, the idea is good, and something definitely could be done there. The link is a good example and a worthy thought, either way.

March 30th, 2008, 04:34 AM
I would add that it's not a good idea to divide the world into polarized camps such as non-technical users and geeks, and choose appealing to only one camp under the "Ubuntu is for human beings" cliché. The release notes should either appeal and be meaningful to a degree to both technical and non-technical people, or only contain accurate, to-the-point information, including a sane dose of technical specifics, leaving the "plain English" to some other form of marketing material.

The author also makes no mention of the fact that what he's "translating" is the beta release notes.

March 30th, 2008, 05:15 AM
plain english (or whatever) language would be great for a user manual, though there is always going to be some technical info required, and needed.

the main point is it should be accurate and factual, imo,

March 30th, 2008, 05:23 AM
I think explaining the jargon in "plain english" would allow it to be more understandable without sacrificing accuracy.

Saint Angeles
March 30th, 2008, 05:33 AM
what about both? speaking it in plain english but with words highlighted (links) that point towards more techincal stuff..

use the best of both sides.

March 30th, 2008, 11:39 AM
just combine a 'middle ground' with both the easy to understand, full sentences and the most important technical terms and names with an in-line 'popup' on mouseover for any terms the user is likely to need explanation for.

Tux Aubrey
March 30th, 2008, 12:56 PM
I'm not particularly technical, but I would normally assume that "release notes" would contain factual and technically accurate descriptions of changes. They aren't directed at new users so much as those who would be anticipating or evaluating the need to upgrade. By definition, this audience would have a higher level of understanding that those that had never seen the product at all.

RNs are not the place to provide "advertising copy" about the distro as a whole.

Both forms of documentation are necessary and I agree that Linux in general does not do the second function well. But, boy, its HARD! I do this as part of my job in another field and it is one of the hardest things I have to do. You have to understand the subject matter at several levels deeper than you intend to explain and you also have to understand the diversity of your intended audience.

March 30th, 2008, 01:16 PM
Whenever I see these discussions, I usually point people to, for example the fluxbox man page or the FreeBSD jail page.

Even the FreeBSD ifconfig man page is a good example--while the first part is difficult for newcomers, it makes sure to put in several examples.
At any rate, it is possible to be technically accurate and also understandable. I think it has to do with whether the author enjoys writing documentation or not, but that's just an impression.

For example, the fluxbox man page gives me the impression of being written by someone very enthusiastic about the program who wants people to be able to use it. The FreeBSD jail man page was written by Robert Watson who, I believe, also designed it.

FreeBSD documentation tends, generally speaking, to be better written than GNU docs. Perhaps there's simply more implicit peer pressure to write good docs. OpenBSD states that they don't consider software complete until it has been clearly documented, and one can't accuse them of catering to newcomers. :)

That being said, with Ubuntu's stated number one bug being that WIndows is more popular, its documentation also tends to be excellent. I often send people from other distributions to Ubuntu docs for clear expanations.

Actually, trollish though it sounds, MS has excellent, centralized documentation as well. Ever since Windows 2000, even their help has been helpful.

chucky chuckaluck
March 30th, 2008, 03:34 PM
in my experience as an end user trying to learn open source software, what i find missing is the first page of the instructions (the ones that take you from "turn power on" to wherever they normally begin). also problematic is when plain instructions to a piece of software make reference to assumed working knowledge of another piece of software (usually one i've never heard of). however, i see the example posted of 'plain english' as a dumbing down that sounds more like an advertisement than an explanation. instead of streamlining the toilet training process it's like saying "it's ok to **** your pants for the rest of your life". linux can be learned, especially with distros like ubuntu and forums like this one. learning makes us better and gives us more control over our own lives. having things handed to us as we are makes us stagnant little blobs dependent on those spoon feeding us.

(might have gotten a little carried away here.)

March 30th, 2008, 04:57 PM
Release notes are for technical users, not everyday users.

Take a look at the release notes for the Mac OS X 10.5.2 update:

Do you think most Mac users know what a kernel panic is?

It's okay to try to create marketing copy, but marketing copy is not the same as release notes. And the mentioning of names of programs shouldn't be something to shy away from.

March 30th, 2008, 05:18 PM
While I agree that jargon can be hard for n00bs I don't think that we should stop using it in release notes and in other places. The reason is that Jargon arises around any technical field were certain specific information needs to be condensed in a way to make it easier to relate quickly. Also usually when you get the information relayed in plain English it is made more general and less precise so that it can be more easily conveyed. When left in jargon it is more specific and accurate. This allows the more technical person to make decisions based on that jargon that the non-technical person wouldn't even know existed. So I think its good that plain English explanations exist but they shouldn't be touted as replacement for jargon.

March 31st, 2008, 12:48 AM
As I have said,
I don't have an idea on how this kind of "plain English" is to be put on ubuntu.com but I just want to share about it anyway. After all, Ubuntu is supposed to be Linux for human beings.

I don't exactly know how plain English is to be put on the site or anywhere else. It's just that plain English makes sense to me because it helped me understand. I don't mean removing the technical release notes because those are for beta testers. Help me think of ways to make it easier for people who are not familiar with the jargon who tend to face the jargon. :)

March 31st, 2008, 01:08 AM
Realese note, schmelease notes, I'd take a webpage like that any day of the week (well, actually, I would just download the darn thing and figure out all the new stuff for myself, but if I had to chose). I would also take a sentence like "the new soundsystem is just fantastic." Then I would take ten of these sentences, compare them to each other, and if all ten states that the new sound system is fantastic, then it would probably have something good to offer. On the other hand, a sentence like "The new pulseaudio features libraries from blah-blah-blah" says nothing at all to me about usefulness or quality, or even whether it is actually going to work after I've installed it.

I stay well clear of them technical notes (leave that to the developers), and stick to real people's reviews of the product. So I agree with the OP, this kind of first-experience non-technical, even dumbed-down language, wouldn't be a bad thing for the people who just wants to know what the hell that darn application does.

March 31st, 2008, 01:49 AM
Release notes are for technical users, not everyday users.

Take a look at the release notes for the Mac OS X 10.5.2 update:

Do you think most Mac users know what a kernel panic is?

It's okay to try to create marketing copy, but marketing copy is not the same as release notes. And the mentioning of names of programs shouldn't be something to shy away from.

The release notes accumulate with every milestone (alpha, beta, RC) release, and then form the document titled the Ubuntu 7.10 More Info (http://www.ubuntu.com/getubuntu/releasenotes/710tour) page on the Ubuntu website. The Ubuntu 7.10 Release Notes (http://www.ubuntu.com/getubuntu/releasenotes/710) page is separate. The latter is what's intended for a technical audience. The former should also speak to a non-technical one.

Take a look at http://www.ubuntu.com/Testing to see how new stuff has been added on top of the previous document with each milestone, finally leading to the beta. At release time, with slight modifications, the features listed in the beta will become the 8.04 "More Info" page (bad naming, by the way), and the caveats that still exist at release time will be moved to the 8.04 Release Notes page.

In other words, the marketing copy and the release notes are separate in Ubuntu, like in OSX. The problem is that the marketing copy doesn't speak very well to its audience.

The author of the blog post is committing a fallacy by calling his subject matter the "Ubuntu Hardy Heron 8.04 Release Notes", simply because Ubuntu Hardy Heron 8.04 isn't released yet, and what he's writing about are the notes regarding the beta release. Beta release notes are intended for beta testers, and beta testers are by definition not a non-technical audience that need the kind of "plain English" that he advocates. Actually, mentioning the traits of a pre-release version with such language would fool non-technical people into thinking it's a release intended for them.

But he also has a point, because it's these very notes that will form the basis of the final "More Info", probably without much modification. This is problematic.

We probably need two different ways of conveying release information, without being divisive, without discrediting the upstream projects that make up Ubuntu, without alienating any reasonable part of our audience, and without making things too vague or overly specific. It's not an easy task, and the current scheme of things does have lots of room for improvement.

I'm thinking of drafting a specification (https://wiki.ubuntu.com/FeatureSpecifications) that aims the produce a set of guidelines for producing the above, which I'll present for discussion in the upcoming development summit. There are plans by others to produce a set of "release notes, but for Universe", and it should probably involve that effort too. I'll drop a link here once it's ready, to get feedback.