WikiWOOD:Layout

From WikiWOOD

This WikiWOOD Guide to Layout is a guide to the basics of laying out an article. It is a summary of what articles should try to look like and how they should be organized. The only exception are Portal pages which are styled somewhat differently than regular articles.

Purpose and Scope

This guideline provides suggestions for the structure and content of all pages within WikiWOOD. It is intended to provide some level of continuity throughout WikiWOOD. It may also provide editors with ideas for content they can add to articles they are writing. It is a guideline, not a set of rules, and improvements to it are welcome. It does however contain some do's and don'ts that must be adhered to for reasons of libel and copyright, and not to create spam.

There are also layout guides for specific subjects that aim to detail the structure and content of specific types of articles. If you can't find one that is appropriate to the article you are writing, consider writing a layout guideline yourself.

This guide is not about how to use wiki markup (see Help:Editing for that); nor is it about writing style (see WikiWOOD:Manual of Style for that).

Article Structure and Content

Lead section

Unless an article is very short, it should start with a lead section consisting of one or more introductory paragraphs. The lead is shown above the table of contents (for pages with more than three headings). The appropriate lead length depends on the length of the article, but should be no longer than four paragraphs. There is no heading above the lead section.

The subject of the article should be mentioned in bold text ('''subject''') at a natural place, preferably in the first sentence.

Normally, the first paragraph summarizes the most important points of the article. It should clearly explain the subject so that the reader is prepared for the greater level of detail and the qualifications and nuances that follow. If further introductory material is needed before the first section, this can be covered in subsequent paragraphs. Introductions to biographical articles commonly double as summaries, listing the best-known achievements of the subject. Keep in mind that sometimes this is all that is read, so the most important information should be included.

First paragraph

The title or subject should almost always be part of the first sentence or elsewhere in the first paragraph:

The Pythagorean theorem is named after and attributed to the 6th century BC Greek philosopher and mathematician Pythagoras

If the subject of the article has more than one name, each new form of the name should be in bold on its first appearance:

Sodium hydroxide, also known as caustic soda or lye...

If an article's title has a parenthetical disambiguator, it should not be included in the bold text:

The article Egg (food) should start with "An egg is an ovum produced by...", not "An egg (food) is an ovum produced by...".

Make the context clear in the first few words:

In quantum physics, the Heisenberg uncertainty principle...

Avoid links in the bold title words, and avoid circular definitions. However, most words describing titles should be linked to more detail:

Buddhist meditation, meditation used in the practice of Buddhism, "includes any method of meditation that has Enlightenment as its ultimate aim." (Kamalashila 1996)

Disambiguation

A "for topics of the same name..." line is sometimes put at the beginning, to link to an article about another meaning of the word, or in the case of a link that many readers are likely to follow instead of reading the article. Do not make this initial link a section. In such cases, the line should be italicized and indented. A horizontal line should not be placed under this line.

Body sections

Headers and paragraphs

The number of single-sentence paragraphs should be minimized, since these can inhibit the flow of the text. By the same token, paragraphs become hard to read once they exceed a certain length.

Headings help to make an article clearer and populate the table of contents. Headings are hierarchical, so you should start with ==level 1== and follow it with ===level 2===, ====level 3====, =====level 4===== and ======level 5======.

If all these levels are used, the article is probably getting very long, complex and difficult for the reader to follow, so consideration should be given to splitting the article into several shorter ones on subtopics. The degree to which subtopics should appear in a single article or be given their own pages is a matter of judgment and of controlling the total length of the article.

Level 3 headings are not easy to distinguish from Level 2 headings. Consider skipping Level 3 and using Level 4 headings instead. Level 5 generates text that is smaller than normal paragraph text, and should probably be advoided.

Articles generally comprise prose paragraphs, not bullet points; however, sometimes a bulleted list can break up what would otherwise be an overly large, grey mass of text, which is particularly helpful if the topic requires significant effort on the part of readers.

Bulleted lists should not be overused in the main text, but are typical in the reference and reading sections at the bottom. Just as for paragraphs, any sections and subsections that are very short will make the article look cluttered and inhibit the flow. Short paragraphs and single sentences generally do not warrant their own subheading, and in these circumstances, it may be preferable to use bullet points.

An alternative to bullet points or very low level headings is to use an indent (start the paragraph with a colon) and use bold text or italics for the first few words which should act as a heading.

Between paragraphs and between sections, there should be only a single blank line. Multiple blank lines unnecessarily lengthen the article and can make it more difficult to read.

If the order in which sections should appear is not clear, use an alphabetical or chronological order, such as in the case of different species of tree.

If a section is a summary of another article

When a section is a summary of another article, it should have a link between the section heading and the text. It looks like this:

Main article: Skew chisel

This should be done using Template:Main to maintain style throughout WikiWOOD. Upto ten links can be used, and alternative labels can be specified. See Template:Main for syntax.

"See also" for one section

If the "See also" refers to a particular section, references to related articles that have not been linked from free links in the text may be placed between the section heading and the text. It looks like this:

See also: Skew chisel (woodturning) and Skew chisel (woodcarving)

This should be done using Template:See also to maintain style throughout WikiWOOD. Upto fifteen links can be used, and alternative labels can be specified. See Template:See also for syntax.

Standard appendices and descriptions

Certain optional standard sections should be added at the bottom of an article. The plural form of the section name should be used.

Although the preferred order is as listed below, it is permissible to change the sequence of these ending sections if there is good reason to do so. However, if an article has both "Notes" and "References" sections, "Notes" should immediately precede "References".

Quotations

Under this header, list any insightful quotations that are appropriate to the subject.

"I have also heard many woodworkers talk of revealing that which is hidden in the timber. This is all very humble, but it too often reflects a willingness to rely on quality of wood to carry a poorly designed or badly executed piece of work." — Richard Raffan, Turned-Bowl Design (1987)

Usually, the most relevant quotes can be placed directly into the article text in order to illustrate the topic, and only a few quotes should ever be part of such a section.

Notes

A footnote is a note placed at the bottom of a page of a document that comments on or explains a part of the main text.

The connection between the relevant text and its footnote should be indicated with a number which is used both after the text fragment and before the footnote.

(At this time, WikiWOOD has no means of automatically linking a point in the text to the correct footnote.)

References

A reference is a note placed at the bottom of a page of a document that cites a reference for a part of the main text. It may be printed material or a website.

The connection between the relevant text and its reference is often indicated with a number or symbol which is used both after the text fragment and before the footnote.

(At this time, WikiWOOD has no means of automatically linking a point in the text to the correct reference.)

Layout guides for specific subjects

Many articles can be classified by the type of subject they cover, and they will have certain characteristics in common. The following guides have been written to cover the specific content of these subject classes:

Miscellaneous comments on layout

Links

Adding square brackets ([[...]]) around a word or phrase is an important part of Wikifying articles. This links significant words to a corresponding article that contains information that will help the reader to understand the original article. For example, an article might mention 'natural edge bowls' without explaining what they are, although a brief phrase explaining the term might be more appropriate in many instances. An article about skew chisels might provide helpful background material when mentioned in passing. It is important to follow the links that you have added and check that they lead to the right page. For advice about what to link and what not to link, see Make only links relevant to the context and Manual of Style, Internal links. Useful links that are not mentioned in the prose paragraphs can be added to the "see also" section.

Images

You should always be watchful not to overwhelm an article with images by adding more just because you can. If better or more appropriate images already exist, they should probably be left in place.

Images should ideally be spread evenly within the article, and relevant to the sections they are located in. All images should also have an explicative caption. An image should not overwhelm the screen; 300px may be considered a limit, as this is approximately half WikiWOOD's text space's width on a 800x600 screen. It is a good idea to try and maintain visual coherence by aligning the width of images and templates on a given page.

Some users prefer images to be all located on the right side of the screen (aligned with boxes), while others prefer them to be evenly alternated between left and right. Both options are valid, although in both cases care must be taken for the images not to clash with nearby contents.

In general, it is considered poor layout practice to place images at the same height on both the left and right side of the screen. Not only does this unnecessarily squeeze text, but this might also cause images to overlap text due to interferences. It is usually not a good idea to place an image intended to illustrate a given section above the header for that section. Placing an image to the left of a header, a list, or the Table of Contents is also frowned upon.

When placing images, be careful not to stack too many of them within the lead, or within a single section to avoid bunching up several section edit links in some browsers. Generally, if there are so many images in a section that they strip down into the next section at 1024x768 screen resolution, that probably means either that the section is too short, or that there are too many images.

If an article or section has many images you can use a gallery.

Horizontal dividing line

The use of horizontal dividing lines (----) in articles is not permitted as it conflicts with the formating of sub-headings.