THL Toolbox > Workflow Issues > Toolbox Documentation Editorial Guidelines
Toolbox Documentation Editorial Guidelines
Contributor(s): THL Staff
Introduction
The THL Toolbox is intended to be published for public access, and thus it is important that contributors follow the guidelines included herein to ensure optimal consistency, clarity, and ease of use. This is particularly important since the Toolbox is intended to be collaborative, and thus adherence to consistent principles will be crucial in ensuring that the resultant resources read smoothly from area to area, document to document, section to section.
Make Navigation Easy and Pages Meaningful
It is important to avoid having endless pages users have to click through which makes resources hard to find, and also creates a frustrating user experience. A few tips to avoid this:
1. Make all pages as full of content as possible. Don't create pages that just have a few links and nothing else. Consider taking the most important and commonly used resource of those links, and incorporating it directly into the page in question rather than making it a link. In such cases, put the indexed pages above, and then underneath have a header 2 (h2) which labels that resource and then put the resource right there.
2. Make it easy to navigate directly to what most people will want. One solution is to have a top section in bold, non-headed that says "Quicklinks to Recommended Resources:" which then gives a bulleted list of items to download or reference for which perhaps 75% of the users will be looking. Then underneath that, put "Full Index:" in bold, non-headed text, and give the full links under that in a bulleted list. The Quicklinks should be in that full list, though they might be just sub-components of those fuller pages.
Should a Given Issue Go in the Toolbox Worksite or another Worksite?
We want to consolidate all documentation into the THL Toolbox worksite, and cross-reference to it from other worskites. This should be done rather than creating the WIKI in the other worksite and then referring to it from the Toolbox worksite. It will just make our overall management of documentation easier if it is all contained in one WIKI. Thus if it is a manual of any kind, or explanation of how a tool works, or how to use a tool, it goes in the Toolbox. The one major difficulty concerns Tibetan script, where part of the documentation is technical (how to make a font, etc.) and part is scholarly (namely the documentation of Tibetan script per se). To be consistent, we are placing all the documentation in the Toolbox, with the idea being that Tibetan script is a "tool" or "technology" as much as modern tools are, so that its full documentation belongs in the Toolbox.
The general principle is that things of like intent and function should be consolidated on a single worksite, unless that principle produces conflicting directions - in which case it must be resolved.
Workplans and status reports do not go in the Toolbox; they go elsewhere.
If it is a glossary, it MUST go in the Tibetan Dictionary (if it involves Tibetan) or THL Reference worksites (if it doesn't involve Tibetan). Otherwise we will have Glossaries split over many worskites. At present, such glossaries are the only thing we know of that will be displayed in the Toolbox but will actually be housed in another Worksite.
Make Documentation Self-Sufficient
Write documentation in such a way that a beginner with little experience can understand, at least from the beginning. No one should read the first paragraph and be left with fundamental questions as to what the subject and point of this documentation is - no one. Thus begin with an Overview section that gives the general context for the item in question, so that people know why they should be using the tool or process in question, and how it generally fits into THL's work
In addition, avoid insular and terse references that presume knowledge someone might have. Please do not rely on your own oral introductions being part of the transmission - write as if you won't be around, and someone is going to have to learn what this is about and how to do it purely from the documentation itself. Spell things out in explicit and comprehensive detail, including ways you navigate through a software or online interface to find a specified option, etc. Don't assume a background – write so that any reasonably intelligent person could easily and accurately follow the instructions with a minimum of frustration.
Always make clear WHY one is being told to do something, rather than just saying it should be done.
Explain how to do things in comprehensive detail, including especially how to fill out fields of information in a form or catalog record, when that is a subject of the documentation
Provide URLs at all points - don’t just say "you can find it on the web" or refer to some THL resource and assume someone knows the URL
Don't provide links to extrinsic pages or downloads (such as a spreadsheet) unless there is a truly compelling reason. Having all data on the page makes it much easier to print a single document, as well as more likely that a reader will read the entire set of instructions.
If there is good online or downloadable PDF manual, make that clear at the top of the document.
Use Formal Language Only
Please do not use slang like "pick your poison" etc. There are two reasons. Firstly, multiple people will be working over time on just about every document, and no one uses slang in the same way. It will thus produce jarring dissonance in tone and language if everyone is talking in a highly informal fashion with lots of slang. Secondly, and most importantly, we have an international range of users. People with excellent command of English can have extraordinary problems understanding informal slang. Therefore, while I realize slang can be more colorful, it should be strictly avoided.
Avoid Specific Names and Emails Regarding Contacts
Please do not make reference to your specific name and email. Otherwise, we will have a quagmire of out-of-date references when staff members quit, are sick, go on extended leaves of absence, etc. Instead, go to the top level WIKI in the Toolbox entitled "Who to Contact in THL" and make a new WIKI for the subject in question. This new WIKI then should give a name and email about who to contact, as well as a backup name/email. That will allow us in the future to easily make a change to a single WIKI, and all references to it will be automatically updated. The reason we make a new WIKI for each contact is that then documentation can precisely refer to just that name.
Naming WIKI Pages
Please give WIKI pages proper names when first creating them, not terse names hard to understand, nor lengthy names that become cumbersome to work with, such as in breadcrumbs. Also, in the name of the wiki page do NOT use slashes, semi-colons, ampersands, dashes or other characters that are computer operator characters. Because a WIKI name can only be used once within a given worksite, you should avoid general names such as "Plan" (instead use "Than's Workplan") or "Timetable" (instead use "Dictionary Database Development Timetable") and so forth. Never give a name that isn't properly expressed, such as "SubversionManual" with no spaces between the individual words (also do not use underscores between words - just use natural English).
Put Lists of WIKI Pages in Alphabetical Order
When you are giving a list of links to individual WIKI pages, please arrange them in alphabetical order using a bulleted list generally (i.e. the asterisk character (*) + space before each item). Do not try to order it in some other sequence that is based upon their content. It may make sense to you, but for others browsing through many WIKIs it is much easier to glance down and know that you will also find them ordered according to their alphabetical sequence.
If in some cases the WIKI pages actually reflect a clearly structured sequence of activities, then order them in that sequence but apply a numbered list style rather than bulleted list style. This is done through applying pound sign (#) + space before each item in the list.
Through consistency, users will then come to expect alphabetical browsing, but when they see numbered lists know that the sequence instead reflects sequential phases of activities or processes.
Top headers & Breadcrumbs
The very top of the page should be a h6 that gives breadcrumbs starting with the name of the Toolbox per se, and then naming each level below that which contains in succession the document in question. Each level is separated by a "greater than" arrow >, and should be linked to the level's main WIKI page using its global name. This is done by putting open bracket, name of level, vertical line (the "pipe" character, shift-backslash), global name of WIKI page, and then close bracket. These are put in h6 so that the breadcrumbs will appear to end users in a smaller font which won't distract from the document's main title.
Code like so:
h6 [The Tibetan & Himalayan Toolbox |/site/c06fa8cf-c49c-4ebc-007f-482de5382105/home] > Fonts & Related Issues
…for this effect:
The Tibetan & Himalayan Toolbox > Fonts & Related Issues
Please note that you have to use the global name for the Tibetan & Himalayan Toolbox since that refers to the worksite home, which is a WIKI page called "home." It is important that we name the worksite explicitly rather than say home, since this is what alerts people to the Collab worksite in which the WIKI page is actually located. However, for other pages in the breadcrumbs, you can just use the name of the WIKI for the hyperlink rather than the long global name. An exception is if you find the WIKI name too long for display, and want to use a shorter label - then using the global name allows you to apply a short label for display.
Breadcrumbs should ALWAYS pertain to the worksite in which the WIKI is located. That way if the WIKI page is cross-referenced from another Worksite's WIKI, readers will immediately see the actual worksite in which the original WIKI page is located. Within a worksite, a given WIKI page may be linked to from multiple other WIKI pages. Thus you should think carefully what the MAIN structural location of the WIKI page is, and give breadcrumbs which reflect that principle location.
Then below that make a top level h1 header that names the document in question. This does NOT have to be the same as the name of the WIKI, though it should be based upon it of course.
Format of Headers
All headers should be written in Title Case, with words other than "of", etc. having an initial capital.
The top header should be consistent throughout a worksite and try to make clear the subject. It may also be advisable to repeat the general subject in the header and hyperlink it back to the home WIKI page. For example, in the Toolbox WIKI, it is confusing to just have top headers that say "Audio-Video", "Tibetan Texts", etc. Readers may come to such a page and expect to find status reports, or even actual resources, rather than technical documentation. In addition, we don't want to rely on the breadcrumbs to inform users that this page is part of our Toolbox. Thus the title should follow the format of:
h1 Tibetan Texts Technical Documentation in the [THL Toolbox |/site/c06fa8cf-c49c-4ebc-007f-482de5382105/home]
Which renders like this visually:
Tibetan Texts Technical Documentation in the THL Toolbox
In the case of the Toolbox, for more specific areas, you may want to substitute something like "Manual" or the like for Technical Documentation depending on the content of the WIKI page in question.
Likewise, for the Dictionaries worksite, the header for all glossaries would read:
h1 Place Terms: A Glossary from the [THL Tibetan Dictionary Project| /site/d05f4dcc-bdf3-4d7e-00d0-63187febb33a/home]
In this way, at a glance, the top level header tells you what something belongs to and is functioning as, while the breadcrumbs give the precise location.
Please do NOT reproduce the name of the document in a h2 below that. Instead, if there are subdivisions of the document marked by headers, and you have an opening introduction, label it "h2 Introduction"; if there are no subdivisions, just some brief text and other WIKI pagelinks, then you don't need any h2 at all.
Review and Proof your Work
Once you have saved your work, check the presentation for end-users. Proofread for typos and mistakes, and especially check formatting – that lists are lists, etc.
Post Internal Information but Keep It Non-Public in Permissions
We don't want to maintain a separate structure for our non-public information, but at the same time we don't want the public to be seeing things that could expose us to malicious attacks, or that is simply completely irrelevant. Thus keep this in mind and keep such information as separate self-contained WIKI pages that can be kept from public view rather than embedded in broader WIKI pages which also have public information. When you create a new WIKI page in this worksite, the permissions are set to public view by default, so you have to manually go into the "INFO" view and uncheck the public view permissions for such pages to not appear in our public presentation of the Toolbox.
The name of the WIKI page will still appear, but when users from public access click on it, it will give a broken link. Thus to alert public users, the WIKI page should have as part of its name the appended text "- STAFF ONLY".
