Organizing an article
Most articles in the wiki will follow a similar pattern of presentation:
- Sections (a number of sections, from 1 to n). Similarly, each section will comprise:
- 0 to n subsections
- See also
The sections below provide a straightforward description of how the typical article is structure along with clear advice on how to organize a topic that you have chosen to write about. There are also templates available to make the task easier.
As an aside, this article demonstrates the basic organization advocated here.
General organization principles
The article organization described here improves the usability of the wiki in two ways:
- By establishing a predictable pattern of presentation, it increases familiarity.
- Taking advantage of the wiki software's navigation capability, it enable the user to read a complete topic on a single screen with minimal need to scroll, accomodating a variety of screen sizes.
We know that members have valuable expertise to share. These guidelines are intended to help members share their expertise in an accessible format. For authors who have not written for the web before, there are a couple of simple considerations that will help:
Authors are encouraged to use the Section and Subsection headers to break their articles into screen-sized chunks. While this approach is a very rough method of addressing the variability of screen size, it is valuable in terms of readability. By thinking of and presenting topics as organized subtopics, authors ensure that busy readers can find what they need quickly. Wiki articles typically employ more headings and subheadings than print material.
In order to take full advantage of the ability to selectively navigate through the wiki, article layout must allow screen space for navigation aids. A page of a wiki article will therefore look very different, from that of a printed article. Structuring of the document to include navigation links to sections will be a critical component of usability.
In summary, authors should keep the following principles in mind:
- Be as concise as possible.
- Break the topic into logical sections for navigation and linking purposes.
Provide links between pages you create, plus links to other articles in the wiki, where relevant.
Start with an overview section
Since each topic may contain a large number of sections, the first item should be an overview, which should accomplish the following:
- Present the topic in a “nutshell” form,
- show how that topic fits into the overall scheme of mine design,
- describe how the content is organized,
- describe the sequence of steps involved in performing the relevant tasks.
Just as the first section of any article is the Introduction, so the first subsection introduces the idea of the section. For each section, the pattern of introducing the topic and outlining how it will be approached will be repeated. Indeed, in each subsection, the first sentence or two should perfeorm the same function: stating the subtopic to be presented in the subsection and outlining the order of presentation.
The wiki software limits presentation to two levels of subheadings. The article title is the Level One heading. The Introduction is Level Two, while sub-headings are Level Three. Please avoid using further sub-headings.
(Additional levels of sub-headings will generally not be incorporated into the Table of contents, since too much detail detracts from usability)
Layout of page
In the master Table of contents, , each entry is a link to a page for a particular topic, i.e., an article. On the page for each topic, below the title, there will be a local table of contents containing further links to all sections on the page. Hyperlinks will facilitate navigation and will be put in place by the site editors.
The local table of contents is generated automatically when the article is saved. Linking to related articles within the wiki will be the responsibility of the site editors, but if you feel confident to do this, please go ahead.
The term references refers solely to those sources of information that are cited in the article. Any sources that an author consults, but does not cite, during the process of writing, should be listed in the Bibliography.
References are important for the following reasons:
- They provide links to the literature for readers who wish to obtain more details.
- They provide links to supporting material that is not essential in the handbook (it is not meant to be a textbook)
- Links to the peer-reviewed literature provides credibility, and situate the article in the context of current knowledge and practice.
- They increase the educational value of the wiki for upper year and graduate students.
Authors are therefore requested to include credible references wherever possible to support their contributions.
See Shrinkage stoping for an example of a brief but useful Reference section.
In addition to the references cited in the article, there may be other sources of information (websites, books, guides, informal reports) ) that the author finds useful and would recommmend to readers. These should be included in a Bibliography. Sources included in the bibliography will be more useful to readers if, for each entry, the author includes a few sentences that outline why it is included (perhaps it is a classic must-read text, or maybe it has particularly helpful diagrams that explain a process).