GEODESC user guide editor
- jr_fackler (Unlicensed)
Purpose of this guide
Basic guidelines for editing JOIDES Resolution laboratory user guides exist already at https://wiki.iodp.tamu.edu/display/LMUG/Wiki+Rules%2C+Guidelines%2C+and+Resources. The purpose of this document is to detail additional guidelines for the integrated set of GEODESC user guides to ensure functioning and consistency in the process and product.
How to access the user guides
Starting in September 2022, the 'live' instance of the set of GEODSESC user guides will be located on the JR shipboard Confluence server, along with all other shipboard lab user guides. Edits from shore will have to be done in one of two ways:
Make slow connection to ship server
Send edits to a staff member on the ship who implements the changes.
To access the user guides:
Get a shipboard Confluence account, and instruction, from your IT representative.
Read the TAS guidelines at https://wiki.iodp.tamu.edu/display/LMUG/Wiki+Rules%2C+Guidelines%2C+and+Resources
Read these guidelines.
Select the GEODESC folder, then the user guide.
Basic formatting
The user guides are all set up as one-page document - you never have to create a page.
The page layouts are set up as described in the TAS guidelines:
The first section has two-columns and a Table of content (TOC) macro in the left column. The right column can be used for important information or some 'decoration' (an image).
The second layout section has one column. The entire user guide can exist in that one section - we don't anticipate reasons to create more layout sections.
Use the existing heading formats, bullets, numbered list etc.
Bottom line: keep this simple.
If you want to learn more about Confluence, simply google your question (starting with ‘confluence’). You will quickly find your answer.
If you happen to experiment with the macros available for special effects, and if you find one you like, let's make it a group discussion and decision, don't just implement it.
Linking
Links from application pages
User guide sections are linked from the application pages so a user clicking the '?' button lands at the linked section heading on the Confluence page in a new browser tab. Our goal is to use the exact same title for the application screen and the matching user guide heading. The buttons triggering the screens should also have the same words as a label unless they are generic short terms such as Add or Edit and are clear in the user interface context.
The links in the applications use the exact heading words, modulated by the Confluence linking syntax. Changing the user guide heading breaks the link. Therefore, do not change headings unless (a) it is really necessary, and (b) you follow up with a developer to fix the link. The user guides are organized such that changes to headings should be unnecessary, but no guide is perfect - just be careful.
Links to glossary
The glossary is where all major concepts and features are described with the goal of having them described (and updated) in only one place. That means that all other user guides make frequent reference to glossary items via hyperlinks. The links are based on the glossary section headings (the titles of the glossary items). Look at an existing link when you are in the edit mode to learn how Confluence requires the links to be formatted. It's simple: add the section heading with spaces removed to the page name, separated by the pound sign, as in 'GEODESC glossary#CatalogManagerapplication'.
Inserting images (screenshots)
When you insert an image, it is added to the page as an attachment. The place in the document where you insert the image is just a display of that image. This has a few ramifications.
You can display the same image in multiple locations in the document, without adding another attachment.
You can display a file that's attached to a different page of the same Confluence site, if you know the name of the file (for example, the overview diagram in the overview guide could appear near the top of all GEODESC user guides).
When you delete the display of an outdated image, the attachment stays with the page unless you explicitly delete the attachment. You can do so while not in editing mode, from '... > Attachments'. Each contributor is responsible for cleaning up that way otherwise we end up with countless redundant/outdated images attached to each page.
To insert a screenshot in the page, you need to create it on your device first and store it locally. Make it a habit to name the screenshots in ways that will help you and others manage the asset attachments in Confluence.
If possible, use the UI screen name that the image was taken from, and then enumerate multiple images according to the workflow (e.g., Edit template 1, Edit template 2,...).
If that is too generic (case of capture sheet), use the feature or function name (e.g., 'Add samples 1, Add samples 2,...).
Add a number in front to sort the images in the order they appear in the document. Just add decimals if needs, e.g., 17.5_image_name to go between 17_image_name and 18_image_name.
Writing style
Sentence style
We are aiming at a professional, efficient technical writing style. Therefore, we welcome each other's continued editing of our user guide contributions towards precise, direct, instructional or explanatory sentences.
Users want to read as few words as needed to get the information. The easiest way to achieve this is to use imperative (directive, instructional) sentences as often as possible, particularly in bulleted lists of steps to execute. We will also be using descriptive paragraphs.
Things to minimize or avoid:
Passive language.
Weak, generic verbs (be, have, occur...)
Sentences using ‘there is’ or ‘there are’, these terms are never efficient expressions in technical writing. (This has been a pet peeve of mine in editing documents for decades and I was happy to find documents that explain it in detail - see links below.)
Unnecessary 'filler' words and phrases, including ‘please’, ‘congratulations!’, etc. (many good examples given in the 'gato-docs' link below).
Look at what the pros say:
Capitalization
We are using the sentence case throughout, i.e., capitalize:
the first letters in sentences, titles and labels
first letters in proper nouns (and other words per special rules, as in taxonomy)
acronyms.
This is also the general guidelines of IODP Publications, and that of most other publishing enterprises, user interface designers, and software companies,
References for sentence case from the Web:
The standard capitalisation of an English sentence, with the first letter uppercase and subsequent letter lowercase with exceptions such as proper nouns or acronyms. (en.wiktionary.org)
A mixed-case style in which the first word of the sentence is capitalised, as well as proper nouns and other words as required by a more specific rule. This is generally equivalent to the baseline universal standard of formal English orthography.
In computer programming, the initial capital is easier to automate than the other rules. For example, on English-language Wikipedia, the first character in page titles is capitalised by default. Because the other rules are more complex, substrings for concatenation into sentences are commonly written in “mid-sentence case”, applying all the rules of sentence case except the initial capital. (en.wikipedia.org)