Every now and then I like to plunge myself into the deep end of website design. All of what I know is self-taught, and I’m always curious to figure out what good websites look like. I’m a particular fan of minimalist websites that have a clean, simple look. More recently, I’ve been trying to play around with WordPress. Lucky for me, they had just upgraded to 3.0, which means it’s hard for me to tell whether something is going wrong because of something I did, or because the new version is unstable.

Anyway, the Internet is great for self-learning; but it’s not great for people who aren’t the greatest at writing guides. Some of these guides are written so poorly that the only people can understand it are people who don’t need to read the guide.

Here are some choice examples. I wanted to see how people define “class” and “id” in HTML, so I googled it to see what pages come up. One of them says:

Definition and Usage

The class attribute specifies a classname for an element.

The class attribute is mostly used to point to a class in a style sheet. However, it can also be used by a JavaScript (via the HTML DOM) to make changes to HTML elements with a specified class.

[Source]

Mmmmkay, that probably makes a lot of sense for a programmer but not a whole lot for a novice. I can understand what it says but I wonder if someone just starting out can as well.

Here is another one:

ID

The ID attribute uniquely identifies an element within a document. No two elements can have the same ID value in a single document. The attribute’s value must begin with a letter in the range A-Z or a-z and may be followed by letters (A-Za-z), digits (0-9), hyphens (”-”), underscores (“_”), colons (”:”), and periods (”.”). The value is case-sensitive.

The following example uses the ID attribute to identify each of the first two paragraphs of a document:

<P ID=firstp>My first paragraph.</P>
<P ID=secondp>My second paragaph.</P>

The paragraphs in the example could have style rules associated with them through their ID attributes. The following Cascading Style Sheet defines unique colors for the two paragraphs:

P#firstp {
color: navy;
background: none
}

P#secondp {
color: black;
background: none
}

The paragraphs in the initial example could also be used as a target anchor for links:

<P>See <A HREF="#firstp">the opening paragraph</A> for more information.</P>

Note that old browsers do not support the ID attribute for link anchors. For compatibility, authors should use <A NAME="...">...</A> within the element instead of ID.

Since ID and A’s NAME attribute share the same name space, authors cannot use the same value for an ID attribute and an A element’s NAME attribute for different elements in the same document. Also note that while NAME may contain entities, the ID attribute value may not.

[Source]

Writing guides of any kind is not easy. It’s like following a recipe. Well-written recipes might not require a lot of prior knowledge. Writing a technical guide is complicated, and these guides were probably not written with the novice in mind. But it’s likely that a novice who is trying to figure out how to make a website to google these terms and be completely confounded by these guides. I don’t think people are taught how to write technical guides, and it’s definitely a unique skill to be able to do it well.