Clever Hamster

BlogEngine (dotnetblogengine.net) is an open source blogging platform based on ASP.NET; at quick glance, I don't see plugins for organizing/publishing printable outputs, but worth a look for .NET shops. Thanks to Tom Johnson for surfacing it: http://idratherbewriting.com/2010/06/23/can-blogs-work-as-a-web-platform-for-help-organizing-content-16

Keys to short-term memory, such as reinforcing with 20 secs: http://theelearningcoach.com/learning/20-facts-about-working-memory/

Must-know information about intrinsic motivation (summary of Daniel Pink's book Drive):

Kiplinger ranks Austin #1: http://www.kiplinger.com/magazine/archives/10-best-cities-2010-for-the-next-decade.html

Better API documentation

Dr. Dobbs Journal hosted Jim Dempsey's blog The Lost Art of Writing Good Documentation, where he points out the shortcomings of generated API documentation. Good function documentation, he argues, includes everything the reader needs to know:

1. #include file list as appears in an application
2. Function prototype
3. Compatibility table
4. Sample of function call
5. Descriptions of required access flags
6. Descriptions of optional access flags
7. Descriptions of mode flags used when creating a file
8. List of return values
9. List of related library functions
10. Complete working example program using the function

What he most wants -- and what is so miserably hard to provide -- is comprehensive coverage that minimizes the need for readers to continue searching and clicking off the page to gather the critical bits of information they need to master a function. Worse, he says the open source project he sites requires readers to have open legacy documentation for simultaneous reference and comparison (which is about as user unfriendly as documentation can get).

The takeaway here may be that we should configure our automated documentation tool templates to generate more placeholders for the information that needs to be human-supplied later, and let those placeholders be the goads to drive us to exert the effort to give readers what they need. The goal: high-value documentation that saves developers hours of tedious research on new functions.

Everything is a balance; every shop tries to allocate just enough but not too much time to documentation.  The temptation is to do less and wait for feedback, asking for more. The danger is that this presumes the SDK users, now disgruntled, will engage enough to do so.

Blogs by tech writers doing Agile

Last week STC Austin hosted a panel presentation on documentation in agile shops, which I presented with Marilyn Rogers and Melissa Burpo. Following up on a request from the audience, Melissa compiled this list of blogs in which technical writers address Agile documentation and processes:

• http://heratech.wordpress.com/
• http://www.idratherbewriting.com/
• http://justwriteclick.com/
• http://ffeathers.wordpress.com/
• http://marilynsrogers.wordpress.com/
• http://agiletechnicalwriter.com/
• http://blogs.atlassian.com/developer/edawson/
• http://www.cleverhamster.com/
• http://greyfiti.com/

Which ones did we miss?

What is technical communication?

I agreed to be interviewed by a student in a technical communication course, and here are my answers to her:

What is technical communication, in your own words? 

It's the job of transferring knowledge, offering instruction, and building understanding of technical subjects in those who need it. Often it takes the form of Help, manuals, references, articles, and training materials. Its media can be written, visual, auditory, or animated. To serve the greatest number of people, technical communication should follow universal design, which means the media should be usable by both young and old, foreigners and non-native English speakers, the handicapped and impaired. Its value is measured in how well it meets the needs of the audience being served.

What are some of the characteristics of your job?

My job divides my time among meetings, communication (email, instant messaging, forums), research, and writing. There's a tremendous amount of self-teaching in this job: since I work with very technical people, I strive to teach myself as much as I can before interrupting any of them to help me. It's a job that can be done by telecommuting, if the organization has virtualized all of its resources and has adopted virtual communication tools (for web conferencing, group chat, threaded conversations), which are consistently used by all the teams. 

What might distinguish it from other forms of communication? Why even is it important?

Technical communication differs from creative writing in that it's all about the user being served and nothing about personal expression: my writing shouldn't be noticeably "mine", distinctive in tone and style, to impress people. Good technical writing, if anything, tries to be invisible (not make you notice it). Technical communication differs from business writing in that it's all about serving a knowledge transfer goal, a learning goal in a user, rather than meeting a business objective (which requires writing for persuasion, authority, etc., to get people to do/believe things that benefit your organization). Technical writing focuses on the truth of the subject matter, and it has higher ethical standards, especially when it involves science and health/safety issues. It's public service, not art or salesmanship. It's more about being an effective teacher than an expressive author.

What tools and skills are needed to produce it?

The writing side of technical communication requires training in proofreading, editing, composition, rhetoric, and (preferably) journalism; being already strongly talented in verbal communication is very helpful, because a technical writer needs the writing part to be quick and easy, since so much energy is required to handle the technical content. The common tools specific to software documentation are listed here: http://hat-matrix.com/tools_list/. However, documentation is increasingly moving to web, wiki, and CMS environments, so it's good to get comfortable with those: http://www.cmswire.com/cms/products/

The visual side of technical communication is helped by training in graphic design, illustration, digital publishing, typography, interactive design, web design, animation and modeling, imaging and video. Adobe products are typical of the type of tools you'd need to master.

In addition, most jobs require mastery of Microsoft Office products, as tech writers are considered resources for word processing and layout assistance throughout most organizations.

How do you like your job? Do you enjoy it?

I love my job because I have a lot of freedom to create solutions to information problems I see. I get to write and rewrite (which I love), I get to design, I get to help folks who are less technical than me, and I get to learn new things endlessly. It's a good fit.  :-)

LEGO League: Winning research on accessibility

This Saturday, my 4th grade daughter competed in the qualifying competition for her region's FIRST LEGO League, the LEGO robotics organization that blends science, programming, and technology into a compelling team sport. I felt sad that she'd put in all that effort and would leave empty-handed, for the odds were strongly against her team: the elementary teams competed on the same level as the middle schoolers, the home-schooler teams had far more time to devote to their projects than the public schoolers, her elementary teachers and teammates had never participated before, and they started a mere eight weeks ago, against the year-long preparation of many teams.

Yet her Purple Sage Riders got called up for a first-place award and were placed in the half of teams selected to move on to the next level of competition. Amazing! The award they won was for their research project and presentation, which was to have them find compelling applications for robotics development. Their design? A robot to assist those with physical limitations in obtaining items on high store shelves. My daughter pushed for this topic, motivated by memories of watching her grandmother struggle to reach things while leaning for support on her walker. The second-place research award also went to an accessibility project, where another elementary team designed a robot to help one of their disabled classmates to make it to a playground area that was inaccessible before.

This theme of shaping technology to serve humanity will continue next year: they announced the topic as being biomedical engineering, using robotics in the human body itself to solve problems and limitations. Go, Riders!  :-)

See all photos.

Energizing organizational Facebook pages

Here is a summary of the advice from the interview, Pimping out your Facebook Page, in which Building43 gets help from Caitlin O’Farrell, the program manager for consumer marketing at Facebook. Tips:

• Optimize the profile image: 200 wide x 600 high (tall and thin); combine/stack images for greatest visual impact
• Encourage members to post photos of each events and then tag themselves and others in them, which distributes the photos onto many walls.
• Rebrand a white label Facebook application for a custom promotional campaign, so that your members can add it to their own pages.
• Customize the page, if possible: using FBML (Facebook Markup Language) to add tabs takes some coding skills. Example: Add Video and Photo tabs (application to import Flickr content).
• Try to get as much information into your Facebook page as possible, rather than just linking off to another site; with 200 million FB users, far more folks will see and share your content.
• Follow specific FB pages that offer guidance, tutorials on presence-building, and links to what other people are building: Facebook for Influencers, Facebook Marketing Solutions, and Nonprofits on Facebook.
• Engagement is best achieved through calls to action, contests, things that require reader response.
• Go to the administrator's view for your page and use View Insights, to learn who your active visitors are, where they're coming from, how many there are, and what postings generated the most buzz.
• Look for numbers of those dropping your page: it can indicate that postings are too frequent.
• Video is the best way to authenticate your page, to convince folks of your identity and integrity.

Tools to check web accessibility

Testing and correcting accessibility problems throughout the development process is all about tools. Here are tips I've collected:

• Support the fewest back versions of JAWS you can: just as with browsers, supporting earlier versions makes development infinitely harder. Current version is 11.
• Fangs is a free screen-reader emulator, a Firefox plugin: http://www.standards-schmandards.com/projects/fangs/
• Study Juicy Studio (http://juicystudio.com/) for Javascript accessibility fixes: they've figured out tons.
• Use Juicy Studio accessibility plugins and toolbar: https://addons.mozilla.org/en-US/firefox/user/320.>
• WebAIM now has an accessibility toolbar: https://addons.mozilla.org/en-US/firefox/addon/6720.>
• There's also a free Web Accessibility Toolbar for IE: http://www.paciellogroup.com/resources/wat-ie-about.html

Finding more tools:

• WAI lists of all manner of accessibility tools (many of which are commercial): http://www.w3.org/WAI/ER/tools/Overview.html
• SitePoint wrote up "12 Tools to Check Your Site's Accessibility": http://www.sitepoint.com/blogs/2009/07/06/site-accessibility-tools/