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
Must-Follow Trends for Tech Writers
Tech writers have always needed to keep up with current technologies. That is the case today more than ever. I’ve been in the field for over 20 years, starting back before online help, back when you copied manuals to put in binders, back when you wrapped up docs weeks before a release because you had to get the book off to the printer.
That’s nothing like today. Changes are so massive, so fast, and coming from so many directions that it is impossible to keep up. Still, it’s important to try. For anything that applies to IT applies to tech writing. Writers must be know something about everything and be ready for it. We’re going to have to specialize and collaborate more than ever before.
Here, briefly, are my thoughts on what I think are some main topics to track. This is a companion piece to my post about Twitter feeds to follow; all apply to tech writing. This post is to explain why to track those feeds. It’s not a comprehensive overview or list. More will come. I may change some of the content here as I come across more information. For today though, this is a beginning. I hope it starts you thinking. Be sure and review the list of Twitter feeds in the other post. Sign up for a few and you can start learning right away.
Cloud Computing
Questions to consider:
Is the app you’re documenting on a cloud? Will your docs be? Should or can your docs be? If your developers have moved apps to the cloud, maybe that’s where you will need your docs for that app to be stored as well (if they’re not already).
If there are security issues for your docs, should they be behind a corporate firewall? Could some be in-house and some in the cloud? If so, then you need to know, as it would be a factor in content-management planning/content strategy for doc setup. Keep up with the security aspect in particular.
Are you developing materials for access over a mobile device? Assume that the cloud is involved.
If there’s a way to cut costs by moving your docs to a cloud, is that something you might want to suggest at your company? Would you suggest a public or private cloud?
In any case, if there’s discussion in your company about moving apps to the cloud, or if they’re already there, you should be in on the planning or know what’s going on. So you might want to keep up on this topic. Here are just a few pertinent articles I’ve found lately through the people I follow on Twitter (my favorite is @cloud_dennis).
2 in 3 IT Managers Have Cloud Funding
http://www.informationweek.com/news/software/hosted/showArticle.jhtml?articleID=219401279
An Essential Guide to Possibilities and Risks of Cloud Computing
http://www.cloudbook.net/an-essential-guide-to-possibilities-and-risks-of-cloud-computing
Mobile Cloud Computing: Is Your Phone Drifting to the Cloud
http://itmanagement.earthweb.com/mowi/article.php/3841611/Mobile-Cloud-Computing-Is-Your-Phone-Drifting-to-the-Cloud.htm
Keep your head in the cloud…
Search
You always need to know about search functionality and trends. That is how people find information in your docs.
The latest news is that Google isn’t using the metadata tag for searches. If your docs are online and you have a Google search button enabled on it, will it find as much if you’ve put everything into a metadata tag? Review the SEO docs on the Google site to find out how it works, and keep it in mind when you write. Don’t write for search, but know how it works.
Keep real-time search on your radar as well. I still have to look into that more. In the meantime, read anything you see about it.
Search Engine Watch has been around from the start; they’re the experts. Follow them!
Social Media
Holy smokes. Where to begin…
Twitter: It’s a great way to push information. I could see using it for submitting questions and getting answers out quickly. You could set up a hash tag for your app or docs. You could set up separate feeds for different aspects of your docs. Then users could just go to that feed and get current info and some in past tweets. You can use it to announce doc and app changes. For gathering and sharing information, it’s invaluable.
Facebook: businesses are definitely using this. It is constantly evolving, and has functionality expansion planned. This could definitely be a place for user input and user-generated information, at the very least. They recently expanded their search functionality; think about taking a look on their blog.
I was at a WordPress WordCamp last weekend, and someone mentioned that a younger person they knew wasn’t using e-mail any more. That person was using Facebook instead.
Now, there’s Google Wave on the horizon. I’m excited to see how that is going to change the landscape. I can’t wait to get my hands on it.
You cannot ignore social media. It’s not going away. It’s also always changing, and doc departments need to determine how to fit it in to their plans. This one is a lot of fun to keep up with.
Agile
If you’re not already working in an agile shop, assume that you will be before too long. Also, you have to keep up with programming trends. If developers are changing their basic work processes, you absolutely have to know how that works. This has been going on for a while, so you need to know about it.
Think about starting to incorporate the processes into your work. On big writing projects, set up daily scrums with the doc team. Leads could be the Product Owner or ScrumMaster. Agile doesn’t need to apply just to programming. If you start using it in your department, it’ll be easier to integrate with the dev team. Don’t wait for this to come to you. Go get it.
When I read about the user stories, I immediately thought of personas. Tech writers should definitely be on the project team and be able to contribute to developing user stories. That is about designing apps to meet user needs and objectives.
You also have to determine how to write docs in an agile environment. How do you plan and design your docs for the long-term while being able to put something out quickly with the latest sprint? I know there are writers out there in the midst of this, so I’ll be trying to get more information.
HTML 5
There are big changes coming with this. It’s not officially adopted yet, and isn’t scheduled to be for several years, but is starting to be used. However, it will impact docs. The most notable changes I’ve seen so far are the effect on tables and possible reduction in use of Flash. These are serious enough for docs that I’m going to begin research on this next.
WordPress
This open-source blogging platform is increasing in use. You need to know CSS and it helps to have a general knowledge of programming in general so you can read a bit of the code. Even if you don’t know that, you could still figure it out.
It’s also very easy to use. There’s a world-wide community that works on and supports development. There are designs already made that you can use and customize as you want. There are plug-ins that enable you to do just about anything you want: set the site up for mobile access, optimize searching, possibly add a wiki.
The point is, it’s all ready. So, poof! You could have a very basic website framed, set up, and running in a day or so, and have the capability to add more functionality through all the plug-ins. Of course, larger sites would take longer to set up. Every theme uses standardized code, so once you learn the basics, you’re good to go. It’s phenomenal, and I highly recommend it to everyone.
…..
That’s a start. I’ll keep adding more information to the site. For more items to track, I’ve also listed some on my Watch List page. Never a dull moment, is there? Especially these days!
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).
The Changing Roles of Writers and Editors
As my friends and family know, I’ve been mesmerized of late by a box of old letters I had stashed in my closet. The letters were from long ago – the late 70s and early 80s – before computers were in use, and definitely before e-mail.
The letters are a joy to read, as they recall wonderful memories and good times with people I’ve not seen in some time, or those I’ll never be able to visit again. Letters were often written over a period of days. Started, put down, picked up a different day. And then that was repeated, until the letter finally found its way to the mailbox.
In stark contrast to this is the technology of today: computers, e-mail, phones. We no longer write letters; we write snippets. In social media, we’re limited to the maximum character length allowed. Server capacity rules. Database limitations rule. Bandwidth matters. Plus we’re all in a hurry, so there’s not much time for reading, let alone writing.
How this applies to tech writing I haven’t completely figured out yet, but I have some ideas. I know content will be more snippet-like with quick delivery and review in mind. Finding, gathering, and monitoring the info is what will gain in importance. How much time will writers spend developing material, and how much time will be spent in searching the airwaves for existing material, determining what’s applicable and useful, and delivering it to users? How can we direct this burgeoning cloud of content?
Folksonomy – Taxonomy – Tags
Everybody puts some sort of tag on their content. Look at any post on any blog and you’ll see tags. What the tech writing community needs to do as a whole is determine some basic tags for all of us to use. This will ensure some consistency, make it easier for people to think of which tag to choose and then apply it, and provide more focused results listings. I’ll write a post and start listing some. Let’s get started.
Editorial Boards
Someone has to moderate all the user-generated content. The role of editor may be expanded from reviewing work of writers only. Writers will still need to prepare information of their own. They will also need to review what others develop to help ensure accuracy – to a point. They will undoubtedly need to look the other way at times, as the freedom to prepare one’s own information must be retained and to ensure that other points of view are represented. However, there will be times when it will be necessary to remove or delete some content. That’s where an editorial board comes in. Set the rules. Establish guidelines for submittals and content. Determine procedures for correcting or removing information. Establish your board now and get busy.
Make it Quick – Whip up a Video
Sure, there are times when it’s preferable to create a planned, long, official nice-looking online tutorial. Much of the time, though, I think you could just take out your little video cam and whip up a gem of a demo. Do we really need to have everything completely scripted and approved and run through the whole process? No. Definitely not. Not everything needs to be polished. Some videos could just be made in minutes and uploaded in seconds. They can’t – and shouldn’t – be too long in duration. For in-house uses in particular, it may be all that’s necessary. And if it’s wrong or outdated? Simply pull out the camera and make another one.
. . . . . .
After reading my letters, I’ve decided to turn off my computer sometimes and write some nice long letters to friends and family. I’ll save my snippets for another day. I don’t want to give up those snippets, but they’re like fall leaves being lifted off the sidewalk by cooling winds: there one moment, gone in the air the next. They’re meant to be momentary. Letters are meant to last.
Tech docs are not meant to last. The technology being discussed is changing so fast that the content is quickly rendered obsolete. People do not want to read that much any longer. We have to be fast, nimble, and prepared to gather, review, and move content quickly.
Might We Become Walking Computers?
What do an article in Wired magazine about attaching a sensor to your running shoe and uploading it via iPod for data analysis, a camping trip, an article about wearing video screens, a scientist husband, a discussion about wildlife parks, office work, and work by a W3C working group have in common? If you can bear with me for a moment, I’ll tell you.
We’re going to turn into walking computers. That’s what I think. This will enable us to leave cubicles and exist in our natural habitats – sans clunky laptops and the like. Crazy idea? Perhaps. Now for an explanation: here is how all this fits together (in my mind, at least).
First, a short while back I found the article on Technology Review about video screens on clothes (There’s a post about it on this blog: Use of Flexible Screens in Documentation.) Development is underway for video screens that can be “worn on wrists, and plastered on clothes.” Ok. So that’s the computer-on-clothes aspect of this.
Second, the Wired article is about how Nike and Apple have developed a sensor that you can hook on your sneaker and which uploads information about your run to the iPod you’re wearing, and you can access the data via iTunes and Nike. That’s more of the computer-on-clothes aspect, but which goes one step further: uploading data.
Third, on our recent camping trip at a lake, there was a duck family that swam around each day right by our campsite. They were in their natural habitat. My husband, in his work and in the group with which he works, focus on natural habitats. We had a family discussion at dinner the other night about wildlife parks and zoos, and I said I preferred to see creatures in their natural habitat. That made me think about office work and cubicles. Nobody likes cubicles. We would all prefer to be in our natural habitat – and an office doesn’t fit that description. Our lake campground was close to a resort town, so we saw many people in town in their natural habitat – one where they could have fun. Everyone was in casual clothes. Not a suit in sight.
Fourth, just yesterday I came across information about a W3C VoiceXML working group. I didn’t know that there was such a thing. Is there a future where one will be able to talk and have some data somehow uploaded somewhere? I haven’t read it in detail, but just the thought of it has my imagination running wild.
So here it is, all wrapped up: maybe we’ll be able to leave offices and work in our natural habitats (whatever or wherever that may be) and wear computers on our clothes, sneakers, and who knows what else, upload data via devices such as the sensor/iPod scenario, use VoiceXML for processing, and download videos and info onto our sleeves. Perhaps this could all be powered by using Velcro to strap a solar-panel strip on said sleeves. Who knows? Who needs a laptop when you just need a shirt, some sneakers and an iPod, and a mobile phone gizmo in your ear?
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