Writing Guide for authors

Overview

This document contains consistent conventions for Computerbank documents, covering the basics which are requested of authors. See other documents in /procedures/documentation for further information.

Table of contents

1. Overview
2. Table of contents
3. Submitting documents
4. Intellectual property
5. Metadata
6. House style definition
7. 1. House style overview
   2. House style points of detail
   3. Document sections
8. Bibliography
9. Changelog
10. To do

Submitting documents

In submitting work to Computerbank you should expect that, during the Publication review process, modifications may be made in order to both apply the house style and fit the document into the Computerbank document tree. By following the Computerbank house style in your documents from the start, less time and effort needs to be spent on this process.

Please do not be put off if you think there are too many rules to learn, if you would like to contribute some useful document(s). We would prefer to have your contribution in whatever form you can provide it.

Please consult the Documentation Coordinator (DC) to find out how you can best contribute to our documentation database. Ask the DC or an editor for help if you don't fully understand anything in this document.

Intellectual property

Copyright

Even if you cite your sources, you must have permission to use work where your work includes a substantial portion of another's. If in doubt, request permission by email or some other means. If the source is unknown, but from a public domain media such as usenet, then attribute it with a note to the effect that if the copyright owner requests you remove the work that you will do so.
It is not necessary to seek permission if your use is consistent with the principle of Fair Use There is a lot of bad advice on copyright, so try to find authoritative information, if you feel you need to research this. ##TODO is there an Australian or International-specific link?
The question of embedding publicly available online works is arguable, but certainly if you do you must acknowledge and link to the parent online source and you should not embed works which are behind password-protected logins. (Embedding is not the same as linking.) ##TODO needs to show what embed means more clearly, at the start
Documents which you publish with Computerbank should be licensed using GFDL or some other open source compatible license.
##TODO policy on linking to sites containing copyright infringing material. Policy on notification of sites to whom you link - this can have a payoff, eg if they move their pages they might just let you know and you might won't end up with dead links. Maybe. Yeah right.

Plagiarism

If you do not acknowledge works from which your work is recogniseably derived, that is plagiarism. Computerbank cannot publish plagiarism, so please err on the side of caution.
Acknowledge your sources even when you are in doubt about their relevence. Readers appreciate this as well, as it gives them more sources for information. For only a few sources, you may acknowledge them in your text, perhaps with hyperlinks if the source is online, but otherwise you should include a Bibliography.
If you need to include content from other sources, make sure you stay within the bounds defined by accepted _fair use_.
To help you to do this, here are some tips:
Try to source your content from a number of sources instead of just one.
Write as much as you can without reference to the source, then compare afterwards to ensure you have not subconsciously copied.
Do not use a chunk of a publication larger than about 10% of that work.
If in doubt, simply contact the author and try to obtain permission. We are a non-profit organisation, they may be quite amenable. If you do this, make sure that the document contains notices attributing the copyright of 'lifted' sections appropriately.
##TODO really check these guidelines

Trademarks, insignia, etc

When referring to a trademark in text, ensure that you use the correct capitalisation as shown in insignia produced by the trademark owner. Do not use trademarks in any manner which could be construed as implying an association between you and the trademark owner (unless you own the trademark or have permission to do so!).
Check whether permission is required and if necessary obtain permission before using recognised graphic insignia and symbols, such as the Australian Coat of Arms or the Australian Aboriginal Flag or colours.

Metadata

At the top of each document, after the title, but before any content, please provide the information requested in this section. This information is known as metadata and will be kept up-to-date along with the document.

Date created

The date when the document was first created in its current form (ignoring more recent minor changes).

Last modified

The date the document was last modified, using format HH:MM YYYYMMDD.

Required skills/skill-level

If the document is a procedure, what are the required skills, or the estimated required skill-level? Indicate this before the procedure description. ##TODO is this metadata, or should it be a document section? As metadata it could be used to generate indexes of material appropriate for begginers for example. This seems useful, but would require some standards.

House style definition

House style overview

The house style of Computerbank is uncluttered, friendly and precise.

• Keep in mind that people from unexpected spheres of experience may find something useful in your document, so try to write in a way that can be appreciated by the broadest audience, rather than the narrowest. And of course, use impartial, non-descriminatory language.
• Computerbank is about doing stuff, so write in an active sense. This means, if you are talking about an action, make an effort to use action words. 'Janet swept the floor' is active, 'the floor was swept by Janet' is passive. Tip: If you can, rearrange your sentences to eliminate 'am', 'is', 'are', 'was', 'were', 'being' or 'been'.
  On a similar note, try to phrase things positively.
• Remember to use diagrams, tables and point-lists to help put the message across as clearly as possible. You should also divide any long document into sections, perhaps even with a table of contents. If the content-portion of a document grows past about 5 printed pages consider whether the document can be broken into two-or-more smaller documents.
• Succinct sentences will ensure that your information is clear and concise, but do keep the text flowing and varied. If the text has become very choppy with short sentences, consider whether it might be a good place to use a point-list.
• Keep paragraphs short - more than five sentences is stretching it.
• If you can choose between a short word and a long word, choose the short one, unless you are repeating the same word often, in which case it may be more important to add some variety.
• Try to avoid unnecessary words. These may creep in without your noticing it, as a lot of common phrases have inbuilt redundency, such as [##TODO find one] which could easily be shortened to [##TODO short version of example]. ##TODO reword more better. For example 'at this point in time' is much better expressed as 'now'. ##TODO other examples?
• Please consult a dictionary if you are unsure of spelling. Computerbank uses Australian English spelling as defined by the Macquarie Dictionary, so use colourise, not colorize. ##A list of commonly misspelled words might be useful.
• For grammar, check the Computerbank Grammar quick reference, and the Australian Government Publishing Service Style Manual if necessary. If it comes down to a judgement call and some punctuation doesn't improve readibility, leave it out.

House style points of detail

Abbreviations/acronyms

Don't use the '.' (full-stop) in abbreviations, unless there is a clear case for confusion with an English word, or the abbreviation is the registered name or trademark of a company or organisation and it includes full stops. ##TODO it is very hard to find real examples for the latter category.
Within a document, except for common abbreviations give an expanded version of the name on the first occurrence with the abbreviation in brackets, for example the Department of Employment and Workplace Relations (DEWR). On subsequent occurrences, the abbreviation should be used.

Appendix

It is probably better to make a seperate document, rather than afix an appendix to a document, and embed links between the two documents where necessary.

Assumptions

If the document is a procedure, what assumptions does the procedure make? Indicate what resources the reader is expected to have available, or what other procedures they are expected to have performed before starting your procedure, for example.

Box

You may have a small portion of logically seperate text, which is associated closely enough with your main document that you want it to appear on the same page, in a box.
##TODO how should the author mark this up? I guess this is going to depend on how they choose to submit their document.
##TODO can silva handle this, or should the author simply make a seperate very short doc?

Bulleted/numbered lists

Numbered lists should be used for tasks which have steps. For lists where order does not matter, eg an inventory, use bulleted lists. Do not use more than three levels in nested lists.

Capitalisation

Capitalise proper names, such as place names and people's names. Capitalise organisations only where you are using the official name of the organisation, then copy from some of their official literature (web-site anyone?). [##TODO rewrite so it is clearer what is meant - be more explicit about situation with mixed case in title, companies that opt for small letter .. are there other situations? .] Capitalise job titles and other individual titles only where you are talking about one individual, so do not capitalise, for example, editors.

Citations

If you want to back up your statements with citations of authoratative sources, for each citation place a number in square brackets after the statement eg like this [2], starting at one and incrementing for each unique source you cite. At the end of your document, include a Bibliography with each of these numbered sources elaborated.

Code/Preformatted text

Indicate blocks of code and other text which should not be reformatted ##TODO how?

Computer input and output

Indent lines of computer input and output. Precede lines of input with an indicator of the expected user prompt, eg
$echo this is a test
this is a test
Leave a blank line after the output, and everything until the next user prompt, or until you stop indenting the text will be seen as being output. If you want to include brief comments embedded into the block of input/output, specify these on their own lines, and indicate italic text.
In the middle of a paragraph of text, you may specify some literal text such as input or output using single quotes for input, and marking output as bold, eg typing at the command line 'echo this is a test' produces output this is a test.
To indicate menu items to click on, use a format like 'File' -> 'Save' -> 'Save as ...'.

Definition lists

A definition list is a list where two components are used for each item, in order to provide information on a number of topics. This section of this document is in fact using the definition list format.
The boundary between using a series of document sections with headings, or using definition list elements, is hazy. However, section headings may be indexed to make a Table of contents, whereas this will not happen with definition list items.
The two components are referred to as the list item (which is the part which corresponds to a heading) and the definition term (which is the information portion for that list item).

Ellipses

An ellipsis is a series of dots ... used for two seperate purposes - to indicate that some text is skipped when quoting (be sure never to change the original meaning ), or else to indicate a long pause and change of direction in conversation.
Do not use a special character for ellipses, just use three full stops without spaces between them, and with a space on either side of the ellipsis.

Frames

Frames are an annoying mistake previously employed by all trendy web-sites. Please do not use them. They often do not print as expected by an uninformed reader, and make it difficult for a reader to determine the URL of a page for reference.
If you need something to appear in a seperate section on the page, denote it with a heading marked 'Box' (see Box above). ##TODO can silva deal with this? I am thinking of a DIV or else a TABLE.

Headings

Headings have no full stop (a heading should not be a proper sentence so should not need one), but can use an exclamation point, dash and commas if they improve things. A heading should never be multiple sentences. Don't make every word start with a capital letter, just capitalise as if it was any ordinary text. ##TODO Word this better.
A document should use only three levels of heading, including the page heading if there is one.

Hyphens

Hyphenate compound words where it makes the word more legible. Do not hyphenate at the end of a line to make a word wrap. ##TODO link to a page of common word spellings, such as web-site or website (which?). Look in the Macquarie Dictionary and see if it can be used to settle such issues, or does it simply list both as viable?
When indicating a sentence pause using a dash, use a single hyphen surrounded by a space on either side - like this.

Images

A picture is worth a thousand words. Use screenshots, graphs, diagrams, photos and flow-charts. Use them often! Ask for help in generating or finding them if you don't know how. Please use .jpg for photo-type images, and .png for graphics and screenshots.
Provide a caption for the image, which should be descriptive. If the image is referenced from the text of the document it may be useful to provide a tag using the format fig 1: This is an example image. Like headings, captions should generally not be sentences, and so should not have trailing full stops.

Names of publications

Names of publications in your text, which are not URLs, should be in italics rather than inverted commas. (URLs should not have any special formatting at all, other than being denoted as URLs.)

Non-discriminatory language

Try to avoid use of gender-specific terms in general. eg instead of something like 'if the user wants to log in she must enter a password' or '... he/she must ... ' try to re-word the sentence to something like use 'to log in, a user must enter a password' or 'for a user to log in, they must enter a password'.

Numbers

In text, express numbers zero to nine in writing. Express numbers 10 and above using digits. In text, use , (comma) as thousand-separators, for example 27,653.00104 (don't use a comma following the decimal point).
Use digits only when referring to a precise quantity, for example the use of the word thousand in thousand-separators above, rather than 000-separators or 1,000-separators. Another example, millions of dollars, not 1,000,000s of dollars.
Units ##TODO a list of correct units such as MB = megabyte, Mb = megabit, km = kilometer, and links to more comprehensive lists of these things (iso). Perhaps this should be in a different Computerbank doc?
Phone numbers ##TODO format for phone numbers, should include international dialling prefix but also be readable by local users without knowing all sorts of stuff.

Parentheses, braces, brackets

( ) = parentheses, { } = curly braces or curly brackets, [ ] = square brackets. All three are types of braces, or brackets.
Generally, in ordinary text, use parentheses. Do not put extra space within the brackets, even if you think it increases legibility. Just try to avoid the situation where you have quotes inside brackets ( ('--') would be better written as '--' and the sentence reworded so that the brackets are not there!).
Use [ ] for indicating, within a quote, text which is paraphrased.
##TODO (a) who cares, (b) is this consistent and efficient?

Quote marks

Use " (double quotes) to indicate speech. If the person speaking is in turn quoting, then use single quotes within the double quotes, for example:
"'Four score and twenty years!' What a long time!" said Bruce.
Use single quotes when you want to indicate that a term is used out-of-context, for example when using a term ironically.
To quote an excerpt of text, instead of surrounding the text with quote marks as you would with speech, format the it as italic.

Underlining

Please don't underline. Hyperlinks are often underlined automatically by convention, so use of underlined text may cause confusion. Use bold or italics instead to make your point. Do not use underlining.

Document sections

Breaking a long document into sections with appropriate headings can really help both the author and the person reading the document. Some useful section headings are proposed below, it is left to the author(s) and editors to choose which headings to use in which documents, but it is recommended that Overview and Changelog [##TODO which ones should be used usually?] be used as a matter of course. You should make up any additional section headings needed.

Assumptions

If the document is a procedure, what assumptions does the procedure make? Indicate what resources the reader is expected to have available, or what other procedures they are expected to have performed before starting your procedure, for example.

• Bibliography

  Where you need to acknowledge a number of works, you should list them at the end of the document in a section labelled Bibliography (put this before the Changelog). For an example, see the end of this document. The works are cited using the following format.

• 1. [author], [title in italics], [date of publication], [publisher].
• For websites, please use the format given below. Omit any fields for which information is unavailable. The version information field should consist of any attached version number or a 'last modified' date, perhaps including the words 'version' or 'last modified', or some other relevent indicator. .
• 1. [author], [title (italics)], [version information], [full URL], [publisher], viewed [date viewed].

• Changelog

  In order to keep track of changes and to ensure that appropriate credit is given to authors, each document should have an associated Changelog at the end of the document (after any Bibliography).
  Please use a definition list in the format given below, using YYYY MM DD date format and HH:MM 24-hour time, adding newer entries to the top of the Changelog.

• [date] [time] [author] [email]

  Very brief description of changes made. Small changes are usually one to three lines, you may summarise major changes.

• Below is an example.

• 2003 05 31 15:45 Charlie Watts charlie@notreal.com

  Add latest info in section How to initialise a LAN card.

Glossary

A glossary of common terms used in Computerbank documents may be available at [##TODO give link and make a common glossary.] You may find it is enough to link to this. Otherwise, please copy the format used in that document. ##TODO because I haven't thought about it.

Headers/Footers

These will be generated automatically using the metadata that you supply, so please do not specify these.

Bibliography

1. Australian Government Publishing Service, Style Manual for Authors, Editors and Printers, 5th Edition 1994, http://www.agimo.gov.au/information/publishing/style_manual, viewed 20 Dec 2003.
2. Ausinfo, ((++Guidelines for Commonwealth Information Published in Electronic Formats++, http://www.agimo.gov.au/information/publishing/formats\)), Jan 2000, Ausinfo, viewed 20 Dec 2003.
3. Geelong Small Press Publishing, Style Guide, http://www.gspp.com.au/style_guide.htm, Geelong Small Press Publishing, viewed 18 Dec 2002.
4. Natural Heritage Trust, Natural Heritage Trust Style Guide 2001, http://www.nht.gov.au/publications/style, Natural Heritage Trust, viewed 19 Nov 2001.
5. Journal of Australian Studies, Submission Information and Style Guide, http://www.api-network.com/jas/style, Journal of Australian Studies, viewed 18 Dec 2002.
6. Department of Education, WA, ((++Department of Education Logo and Style Guide++, http://www.eddept.wa.edu.au/regframe/Documents/DO04003898.pdf)), Department of Education, WA, viewed 18 Dec 2002.
7. Brian J Goggin, Re: No period after abbreviation?, 3 Mar 1998, http://groups.google.com/groups?selm=34ff629b.6790657%40news.indigo.ie, Google Groups, viewed 20 Dec 2002.

Changelog

14 Apr 2004 Simeon Scott shevek@bur.st

Tidy up internal and external links, following move of site.

15 Aug 2003 Simeon Scott shevek@bur.st

Tidy up internal links, they now work. Add email links in Changelog.

27 Jun 2003 Simeon Scott shevek@bur.st

Incorporate feedback from Jan Smith. Rename Style guide for authors to Guide for authors.

12 Jun 2003 Simeon Scott shevek@bur.st

Release First Draft for limited public comment. Plan for Second Draft for wider public comment.

15 May 2003 Simeon Scott shevek@bur.st

Re-markup using new Silva server, reedit.

17 Apr 2003 Simeon Scott shevek@bur.st

Silva markup and reedit. Incorporate feedback from Danny (Snake).

3 Mar 2003 Simeon Scott shevek@bur.st

Split Style Guide into several documents, including this one, Style guide for authors.

18 Dec 2002 Simeon Scott shevek@bur.st

Created document Style guide.

To do

Macquarie Dictionary

Macquarie Dictionary have removed their free access online copy. They want 50 cents per authorised user per year for login rights. Perhaps we could ask them to 'donate' a corporate subscription to cbv.
Alternatively, we could choose a different online dictionary as our reference dictionary (ie one which is not Australian), or otherwise refer authors/editors to hardcopy, and try to get a copy for the office.

Tidy complex lists

The set of various types of list items used in Document sections and probably other areas need rationalising so there is a consistent look and structure.

'To do' document section decription

Provide a description of the 'To do' document section in the 'Document sections' section.

'Status' document section

As above, but for 'Status'.

Code markup style

We need a markup style for code.

Various other items

Various other things need attention, many of them are marked throughout the document using ##TODO as a marker point which you can search for. This really is still an unapproved draft.

Stronger cross-links to other relevent docs.

Perhaps put in a table?

Finalise and get approved this document, then implement style site-wide.