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
Wikipedia to Add Editable Video Functionality
Game over. Print is on its way out. I just read an article about Wikipedia adding video functionality down the road that will enable people to edit videos.
I’ve been figuring that video is key, and that people would take some video already made, come up with their own version, and post it somewhere. I’ve seen such videos on YouTube – not for docs, but for other topics. Functionality for people to “annotate your video, edit your video, and improve upon it–in the same way people have been doing to your text posts” makes it a whole new ball game.
See the article in Technology Review:
Wikipedia Gets Ready for a Video Upgrade
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
In With the New: Video
“Everything is on YouTube.”
So stated my son the other day, in response to a comment about looking to see if something might be there. I’d have to agree with him. Every time I look for something there, I’m surprised. The fact that younger kids think of YouTube as a primary source of information also gives pause.
For a while, I’ve been looking at videos on YouTube and other sites with tech writing in mind. What jumps out is that people use videos in varied, unexpected ways (to me, at least). It’s not just that people are creating videos and putting them up there. They’re also taking news broadcasts and movies and making them their own. For movies, I’ve seen videos where people have taken their favorite scenes, put them together, and added music. While some are similar, you can see that each person gives theirs a slightly different slant or uses different music. What’s important to one person is not so much to another.
Now think of that related to tech writing. You’ve researched a topic, talked to SMEs, and written something up. Still, it’s your slant on what’s most important. You’ve been trained what to look for, how to organize content, and how to prepare the info. With this usage in YouTube in mind, someone could just take what you’ve written and make their own version. Assume that users will (a) make their own videos, and (b) take something already made and create a new version. In may be from something in-house. Perhaps it may be from an external source. This has tremendous potential. Combined with comments, it could provide a wealth of information.
By now, I imagine (I hope) that companies are either using or already in the process of setting up an internal video site along the lines of YouTube. For documentation departments, I believe now is the time to try and move that along. The process may take a while to run through a company. There could be a number of issues to work out: technology requirements, security, processes, and usage guidelines are possibly a few.
We’re always the voice for the users while an app is in development. I believe that we now must be the voice for the users coming in that will expect to be able to post and review job-related videos.
I believe that the role of tech writers will change. We may shift more into content management and development of enterprise information and moderator of user-generated content. There will still be procedures to write and doc sets to create. We’ll just need to make room for whatever comes so the voice of the user is heard. All can participate. I’m looking forward to it.