Minimal Procedure Content: Reasoning
The procedure I wrote about creating a Twitter list uses abbreviated content. This post describes the reasoning behind and decisions made in writing the topic.
Title
Instead of using this:
Create a Twitter List
I opt for this construction:
Twitter List: Create
Reasons
It puts the topic first. You don’t have to dig through the content to get to it. For scanning, you can see immediately that it’s about Twitter lists. If there were an alphabetical list of “creating” topics, where would you find this? I know the training has always been to start topics with an action. However, I think it’s OK to break that rule.
I believe this construction would also lend itself to XML more easily. Twitter could be a tag and database record, as could Lists and Create. From a database design standpoint and rules of normalization, it would be better to have a “Twitter” record that could be referenced and reused more easily. It would make it easier to create tables, build queries, and add programming features to accompanying XSL files. If you have an XML tag/database record that contains just a topic title (e.g., Create a Twitter List) you may have problems down the road. Your database won’t scale very easily.
Also, it provides a way to automatically sort. As an example, I’ve made up some titles to show how it might work
Twitter Feeds: Block
Twitter Feeds: Follow
Twitter Feeds: Unfollow
Twitter Lists: Create
Twitter Lists: Edit
Twitter Lists: Delete
Facebook Pages: Create
Facebook Privacy Settings: Edit
In a sample table of contents (TOC) for Twitter:
Feeds
Follow
Unfollow
Block
Lists
Create
Edit
Delete
Traditional construction (both in title and TOC)
Block a Twitter Follower
Unfollow a Twitter Feed
Create a Twitter List
Delete a Twitter List
Edit a Twitter List
Create a Facebook Page
Edit Facebook Privacy Settings
Content
The audience I’m writing to is tech-saavy individuals that already know how to use Twitter. Any general usage procedures would be covered elsewhere. Content is abbreviated as much as possible, written with mobile devices and small screens in mind.
As I’m planning to include a short video showing this, I also don’t believe it’s necessary to go into as much detail in the written procedure. For example, step 2 mentions a “box at the top of the page (if visible).”
During testing, I closed the box, and was unable to reopen it. Rather than writing a long sentence or two explaining that, I just chose to put in “(if visible)” to quickly note it. Then, in the video, I can discuss it more. Commentary can be provided in a video that would just clutter a written procedure. I see the written procedure and video as a pair. Each has its own purpose.
Video
The video I’ll be adding won’t be fancy or long. I don’t think it’s necessary in this case. There will be times when it’s important to plan out and make thorough, polished presentations and tutorials, but perhaps they don’t all need to be. Allow for something quick to be made, tossed up on a server somewhere, and available right away. I believe we can make some quickly that do not have to be completely polished. Today, speed is increasingly important, as are budget considerations. I think it’s time for doc departments to let go a little. Determine when it’s OK to just get something out fast and when to go the distance and make a full presentation. Times have changed. Does it always have to be perfect?
More
HTML 5: What Tech Writers Need to Consider
Wow. I knew that there were many items to consider when writing documentation these days. However, there is much more than I realized. For example, today I started looking at HTML 5 more in-depth. As I read through the information on the W3C site, it became clear that big changes are in store that will affect technical writers.
In HTML 5, a large number of elements will possibly be relegated to setup in CSS only. The major one I noticed initially is tables, as use of tables is obviously prevalent in docs. It appears that presentation elements will be handled through CSS. That includes everything, basically: width, padding, height, and borders are among the attributes that are changing.
Given all these changes, I looked at the current state of CSS on the W3C website. Version 2.1 is now in Candidate Recommendation status.
Frame support will also be discontinued. I imagine that most people do not use frames at this point. If you are, consider stopping that practice. Frames are also not recommended for mobile devices, and search engines have difficulty reading them as well.
References to Review
HTML 5 differences from HTML 4
Recommendations
Move all presentation configuration to a CSS file
While work will continue to evolve with HTML 5, it may be difficult to know what to include or not. However, I think that at this point, if you’re not already, you can at least focus on moving all presentation configuration to a CSS file, particularly for tables. Use the information on the W3C site as a guide, and realize that development is yet in progress.
Discontinue use of frames
For reasons noted above, it’s best to avoid use of frames.
Keep up with changes
On my Twitter feed, I’ve listed some links related to HTML 5 and will continue to do so. I’ll also note feeds that may be helpful to follow in a #followfriday entry. Keep in mind, too, that this will also affect mobile items.
I need to look at all this in more detail, and determine how it might affect XML and XSL files. For the moment, just be aware: there are even more items to plan for when setting up your documentation. Don’t assume that your style sheets of today will be adequate for docs down the road.
Cut, Cut, Cut your Content and Procedures
Sure. We’ve been reducing word count in procedures for some time. It’s time to do more, however. As noted in an earlier post, we have to think mobile. Think small screens and small devices. Screen real estate will be at a premium.
With that in mind, I’m offering some suggestions on how to cut back. Remember that users are now quite computer-savvy. I don’t think we have to concern ourselves with the level of basic understanding as we did in years past.
Personally, I don’t think it’s necessary to include all the bold type such as that shown in The Old Way example. Those would make the screen too busy, anyway. If you stand back and look at that example, what jumps out at you? Right – the bold type. The main item for each step. You can scan those steps and pull out what you need. When you strip out all the extra wording, you’re left with what was bold in the first place. So why not pull all the extraneous wording? Look at The Old Way bold items and look at the Cut More example. Notice anything? Aren’t they the same?
The Old Way
1. Settings > Contacts Settings > Update Contact Information
2. Click the Permissions tab.
3. In the Access dropdown list, select Global.
4. Click Save Changes.
Cut
1. Settings > Contacts Settings > Update Contact Information
2. Tab: Permissions
3. Access: Global
4. Save Changes
Cut More
1. Settings > Contacts > Update
2. Permissions
3. Global
4. Save
In the Cut More example, you can see that I dropped some of the menu titles. I know that we’re supposed to write it exactly as it appears. However, if you can drop a word so only the main one remains, then go with it. (Contacts is the main term of Contacts Settings; is the Settings item really necessary? Of course, in such a case, a chat with the developers about a UI change might not hurt either.) It would be a judgement call every time. You’d have to see what other menu or screen items there are to ensure that there’s no confusion. If you can cut it though, do so.
I think that we could at least go with Cut or Cut More, or perhaps a combination of the two. Get out your scissors and get to work. Keep cutting until you get all the way down to the least common denominator (going back to the days when I had to break down fractions).
Think Mobile When You Write
Always keep the small screen in mind when you’re preparing your docs. There are some W3C “mobileOK” guidelines to consider to ensure that your content meets requirements. Here are some highlights:
Tables
- No nested tables
- Tables must have more than one row and more than one cell per row
Page Titles
- There must be a Title element in the Head section, and it must not be blank.
Frames
- No frames. These don’t work well for search engines anyway, so it’s best to avoid them.
Images
- No image maps
- Images must have height and weight measurements, and they must be in pixels
- Images must use alt tags, and there must be text in the tag (not blank)
- Transparent graphics for spacing: no large ones
These are just a few items. There’s enough, though, to consider. When you plan your content, think mobile.
Use of Flexible Screens in Documentation
Lately, I’ve come across two articles about flexible screens. One is for small touch screens, the other is about video.
What’s particularly interesting about the video flexible screens is that the article in Technology Review states that there is a possibility that such screens could be “worn on wrists, and plastered on clothes.” Now imagine this for docs: what if, perhaps, you are working in a manufacturing facility and need some instructions on how to run a machine or something. What if you could just push a button on your sleeve and see a video about how to complete that task. Or who knows what else there might be? Could we really have video docs on our sleeves? The article doesn’t give much detail about types of information, but imagine the possibilities…(http://beta.technologyreview.com/computing/22758)
The other article, also from Technology Review, is about small, flexible touch screens. Perhaps you could have a device that fits in your back pocket that maybe could have an online quick reference guide on it? Or other instructions? Docs have to be designed with small devices in mind. (See link in the “A New Doc Strategy” post.)
A New Doc Strategy
In years past, a doc strategy was fairly straightforward: prepare print documents that were either in binders or printed into a book. Then came online help, so both were used. Then PDF was added as an option. For many, that’s as far as capabilities have progressed.
The new reality is that technology is rapidly changing and different methods of access are popping up all the time. Print and PDF, to some degree, are going to fade away. Some sort of online version will endure, but it won’t be what we’re accustomed to.
To wit, here’s yet another example of new technology: bendable, paper-thin screens and mobile device screens that “roll out” to a larger size.
http://www.technologyreview.com/computing/22232/?a=f
http://news.cnet.com/8301-10784_3-9891347-7.html
How cool is that? And how will it affect or impact overall documentation strategy? If you’re developing for mobile access, but the screen can enlarge, but is likely still smaller than a desktop screen, how do you design your docs for all?
These are the sorts of questions that will continue to arise. The simple days of print, online help, and PDF are gone. The idea of a “document” may even fade away.
If I were developing a doc strategy today, I would have the following elements, at the very least:
- Use xml and databases to produce content that can be accessed over intranets and the Internet, including portals such as SharePoint
- Design for mobile devices
- Use online forms to set up docs so that they can be directly input to a database
- Use content management strategies to review, design, and write content accordingly
- Set up video libraries (such as YouTube)
- Use Twitter for tech support and to push information and updates to users