Online groups, summer 2014
A member is updating a software user guide that is for software developers. What is a good method for version numbering to make sure that the differences in the following types of documents are clear? A simple method that will not cause a large 'document history' section in the user guide is necessary.
- 'Draft' document versions that only the writer and the customer see.
- 'Minor' document versions for changes or new features that represent a new build of the software, but not a new software version.
- 'Major' document versions that are related to a new software release. The software does not have a consistent pattern for versions numbers (the release name is more meaningful than the version number).
Members gave many different examples of numbering methods. Also, they gave this general advice:
- The readers of documents must know that they have the correct version.
- Use the simplest method possible.
- The numbering for the documents and the numbering for the software must be different. For example:
- The software does not change, but a correction to a document is necessary.
- A user guide changes because of a change to the marketing strategy of an organization.
- In the revision history or in a 'What's new' section, make sure that the changes to the software and the changes to the user guide are clear.
- Use the product name and the software version number in the title of all documents. Show the document version number on the same page.
- The initial question used the terms 'document numbering' and 'document control'. Document control and document numbering are different.
One member uses the date to show versions because a reader can immediately see if one document is newer than another document.
Members recommended these resources:
A Microsoft Word 2013 file is two A4 pages. Most of the content is text. The document uses only black and one other standard colour. The file size is 57 KB. When the file is saved as a PDF file, the file size of the PDF file is 207 KB.
Is a smaller file size possible for the PDF file? Why is the file size of the PDF file much larger than the file size of the Word file? What software or methods can decrease the file size of the PDF file?
Typically, to decrease the file size of a PDF file, do these things:
- Compress the graphics. You must decide what is a satisfactory quality.
- Remove unnecessary items, such as named destinations. You must decide what is unnecessary.
- Remove embedded fonts and subsets of fonts.
In Word, you can specify things such as the compression of images and the fonts that are embedded.
To decrease the file size of a PDF file, members suggested these products:
- Adobe Acrobat (www.adobe.com)
- PDF Shrink (www.apagoinc.com)
- PDFCreator (www.pdfforge.org)
- Pdf995 (www.pdf995.com).
When I wrote this review, I found 'How to compress a PDF file' on the Adobe TV website (http://tv.adobe.com/watch/acrobat-x-tips-tricks/quick-tip-how-to-compress-a-pdf-file/).
A member will develop documentation and a related style guide for a new product. The member wants advice about the capitalization of product terms. Some examples are "… names of inputs and outputs to the system, such as External inputs, Channel inputs, Direct outputs and Monitoring outputs, and signal processing features, such as Dynamics modules." However, "…capitalising these words within the text will make them jump out at the reader unnecessarily, making the text seem disjointed."
Ideally, use initial uppercase letters only for proper nouns. However, use the same capitalization as the product.
To emphasize terms that are not proper nouns, use one or more of these methods:
- Use a different colour, point size, or font.
- Use bold, semi-bold, or italic text.
- Use shading.
- Use links to a glossary.
Character formatting can become a problem because much time is necessary, specially if you must use character formatting in many documents.
This is a good time to ask users what they like. Ask the product manager to give you permission to contact some users.