Help Files 2.8 Styleguide Notes

Style Guide Notes

Indiana Knowledge Base Technical Writing Style Guide

https://kb.iu.edu/data/apff.html

Alan's initial thoughts

Just kicking off some ideas to get a conversation started. Nothing in stone here...

Use active verbs (avoid passive voice)
Bold the action the user should take
- "Click Site Info in the left menu"
Place action in front and any explanation or additional detail afterward
- "Click Site Info in the left menu" -- not -- "In the left menu, click Site Info."
Express dates with months written out or abbreviated-- 7 Feb 2011 or Feb 7 2011, not 7/2/2011 or 2/7/2011, which are ambiguous across the Atlantic.
Avoid jargon and technical terms whenever possible, especially in page titles; language should be human-friendly (e.g. most end-users do not know what "WYSIWYG" is and will not understand that this refers to the rich text editor within tools)

Feedback from Elizabeth Venstra on Alan's suggestions

First, there are some matters of wording.
- “Use active verbs (avoid passive voice)”---I absolutely agree
- “Place action in front and any explanation or additional detail afterward”, e.g., “‘Click Site Info in the left menu’ not ‘In the left menu, click Site Info’”
  - The latter is a style standard that we’ve evolved at the KB in order to present information to the user in the order in which s/he needs to find it on the screen. It might be clearer why we think this is a good thing in this example: “From the Tools menu, select Options, and then click Account Options” (or whatever; I’m just making this up, imagining a sub-menu that pops out). The user sees the clickable items in the order in which s/he should look for them. Now, cases like that are a little different from the left menubar in Sakai; I think putting the verb first would be unlikely to cause confusion when the place in which the person should look isn’t a clickable name. And, in fact, we don’t always apply the order of operations rule rigorously. So we would be willing to match our style to this standard (at least in cases like the example you gave), if that’s what the Sakai group wants to do. But I wanted you to know why the documents had been written that way in the first place.
Now, about date format – you recommend 7 Feb 2011 or Feb 7 2011. Actually, I doubt specific dates occur very often in the Sakai help documents, but if they do, our existing style standard is February 7, 2011. Given that it would be difficult for us to use a separate date standard for a subset of our documents, and our standard meets your need of being unambiguous, can I just ask you to take our standard on this minor point? – at least, for any documents that we manage that involve specific dates, which, as I mentioned, is unlikely to happen anyway.
Robin writes: Yes, fine. (That was my note.)
“Bold the action the user should take”, e.g., “Click Site Info in the left menu”
- This isn’t really a question of style so much as formatting, and right now, it’s not a request we can accommodate. Let me explain.
- In the markup we use for the help documents, a step that said “Click Site Info” would look like this:
```
<li>Click <mi>Site Info</mi> in the left menu.
```
  “mi” stands for “menu item”. We use this for anything clickable – buttons, menus, tabs, icons, etc. – when the actual text appears on the clickable thing. We also have <code> tags for folders, filenames, drives, user input, etc., and we use quotation marks for things that don’t fit either but appear on the screen, like a section of a web page or something. You’ll notice that <mi> and <code> are more semantic tags than formatting tags. Our style sheet renders <mi> as a bold monospace font and <code> as a non-bold monospace font, but another style sheet could render them differently.
- We are currently working towards a transition to DITA, and when we are there, we will be even more thoroughly in the semantic tagging world---not controlling the appearance of the text, but simply marking up what it is, and leaving the rest to the style sheet. At that time, it might be possible (we haven’t done enough research to know yet) to have some kind of tag like <verb> for words like “click”, which your style sheet could then render in bold, if you wanted to. But we’re not there yet, and in the short run, we’re not going to be able to change our present model to bold the whole phrase without messing up a lot of stuff on our end.
- By the way, even if we could adopt this standard, I would advise against it, personally. I see why you would want to call attention to the verb, since it’s an important word. But having the tags around the specific text that the user is looking for is more valuable, in my view. It provides a demarcation of exactly what they should expect to see. I don’t know if I’m getting across what I’m trying to say . . . and anyway, I don’t have solid research proving that it’s easier for users to follow when they can clearly see the text of the clickable item---it’s just my own instinct. But that’s kind of moot for the short term anyway.
  
  Alan writes: Elizabeth, for the bold situation I think we're on the same page. I was including the verb as well as the object. I'm okay with just indicating the object. The extra detail you provided was great -- thank you!
  
  For the order of information, I am a big believer on "show me what I click first." I perceive this as faster and more focused. If people do in fact have shorter attention spans nowadays and prefer to skim materials, I would rather have the key items up front and descriptions after. Of course, that's my personal preference.
  
  Next, I have a slight concern about how many items to emphasize in the same sentence. I think I would lean toward breaking up sentences if there are too many clicks. I'll try to provide an example below. I admit that I am a fan of step-by-step... literally. I am always open to other options, though! Just throwing this out for consideration.
```
EXISTING LINE FROM RESOURCES
<li>Next to the existing folder, from the <mi>Add</mi> menu, choose <mi>Create Folders</mi>.</li>

WHAT ABOUT
<li>Click <mi>Add</mi> next to the existing folder.</li>
<li>Choose <mi>Create Folders</mi>.</li>
```

Style Ideas - from Elizabeth Venstra - IU KB team

Having a four-letter document ID (docid). For example, https://www.indiana.edu/~sakaikb/display.cgi?docid=arbs is something I'd identify as arbs if I were going to call it up to work on it. I don't know if these are accessible from the Sakai help tool or not - are they? Since we work on individual documents, having the edits identified for each individual document makes the work easier to sort and manage for us, whereas if we get revisions to all of the documents/topics related to one tool in one file, it's much more complicated to sort out what we need to do - although we can do it if we have to. (It just takes longer.) Again, if you'd like, I can generate lists of documents that would show you the docid.
Robin writes: Yes, we need that mapping between document titles and docids.

If you're working on edits to individual documents, by the way, we can take those as soon as they're ready - no need to save them all up and send them to us at once. Of course, we need to know if the changes should be released right away, or held for the 2.8 release. My understanding from Stephen Marquard at Cape Town is that the help tool can only point to one version at a time for all of Sakai, so ideally, we'd manage the transition from 2.7 to 2.8 as much as possible simultaneously - but it will take us some time to actually make all the changes, so we'll need to make changes to documents in advance and hold them for later release, if we can.

It definitely helps to know what has changed in any given document from the current, live version to the updated version you are submitting. So, if there's an easy way to see changes tracked (all at once - not version 1 to 2 to 3 to 15!), great. If someone just says "In step five, change 'Revise' to 'Edit'", etc., that's great too. But just know that we're going to be making all the changes by hand. (It's not really so bad if changes aren't tracked, though, since Word has a nice Compare Versions feature!)

It would certainly help when working on any given document to be able to get in touch with the person(s) who could best answer any questions we have if we don't understand what the revised text means.

We'll try to keep the style pretty consistent, and we'll generally want it to be pretty consistent with what we've already got for the IU version, although I'm open to suggestions about how to improve the style. So, if you think something would be clearer to end users if it were worded differently, I'd be happy to hear it. If you think that a particular way of doing things that we do throughout the documentation would work better another way - involve me in the conversation sooner rather than later, so I can think about whether we want to implement it throughout the repository. But if individual people just change the wording because they like the sound of one sentence rather than another, I may well change it back! - especially if not everyone does it the same way. (Generally, when I get information about changes from our support consultants, I'm looking for them to tell me what is true or false, and I worry about the style on my end.)

On the other hand, I will be relying on the reviewers to give precise information about how clickable items and text on the screen appears, including capitalization, punctuation, spacing, etc. Don't worry too much about formatting those things - I will format them with our tags, depending on whether it's clickable, something you see that's not clickable, a folder name, etc. - as long as it's clear what the actual text of the thing is. Don't worry about things like single or double spacing or whatever, either. I'll take care of that.

Also, on the subject of style, in general we try to make our style fairly minimalist, and we're moving more in that direction as time goes on. So, we've often been simplifying "click the yadda button" to simply "click yadda". For whatever that's worth. Give the users only the information they really need in as few words as possible - but, again, don't worry about that too much, because we'll simplify the style on our end if we can without changing the meaning.

I would suggest avoiding the word "Sakai" unless you think it's really necessary to the meaning. I believe quite a few schools call their implementation of Sakai something else, so as a general rule, I try not to refer to Sakai if I can talk about, say, the tool instead. Or sometimes we say "the application" instead of "Sakai".

Links between documents are not managed like typical href tags, so if the title of a doc is changing, the current title will always appear wherever it is linked. Just so you know not to worry about changing the link text anywhere in any of the docs - all we need is the docid.