Showing posts with label technical documentation. Show all posts
Showing posts with label technical documentation. Show all posts

Sunday, January 06, 2013

Fixing software with documentation at Harvard

Much has been made of Harvard School of Law's online course on copyright law. The course, given by Professor William Fisher, covers a range of topics related to the theory and application of copyright law in the U.S. and other countries. The course is limited to 500 attendees, participating in groups of 25, giving a small-class feel to a massive open online course.
Registration closed on January 3. As a result, we are told to ignore the big registration button on the course page.
Please note that the "Register" button above is not used for HLS1x. The application period is now closed, please see the section "When should you apply?" below for more details.

This is what we call Fix It in Documentation. The way that the HTML page is stitched together, the registration button is one component while the course description below is another. It works well until it doesn't. Apparently, there isn't a way to disable or otherwise change the display once the registration period has passed. So, two sentences in red text tell you that they couldn't change the button and that you can't do what the button says you can do.

Sunday, July 15, 2012

Book review: Managing Enterprise Content: A Unified Content Strategy

There are two big challenge for people  trying to develop a unified content strategy, challenges that Ann Rockley and Charles Cooper's book, Managing Enterprise Content: A Unified Content Strategy, don't overcome.

The first is that most organizations don't care about a unified content strategy.  In every business, there are good ideas that languish because no one high in the food chain cares enough to listen to reason. The costs and schedule delays are too small and spread across too many organizational boundaries for any one person to see a major impact on business operations, expenses, or revenue.

Enterprise content is, first and foremost, about the enterprise, not about the content. The enterprise is an ecosystem that produces content, to be sure, but it's mostly concerned with staying healthy by making sure that no one loses their job because they made a bad choice.

Down in the trenches, the problems are all too prevalent. Anyone who has to write anything knows that someone else is writing almost the same stuff someplace else. Things are slightly out of date or out of phase. To fix it, though, requires a major shift in operations and management. It ain't gonna happen.

The second thing is that users don't care much, either. If the manual or online help is out of date, they'll use Google or Twitter to find the answer. It gets to the point that even if the content is correct, users are so out of the habit of trusting the docs that they'll go to Google or their neighbor or the kid down the street before they'll read a help file.

So, managing enterprise content isn't about identifying types of content, developing a taxonomy that resolves concepts and terminology into a coherent whole, or any of that, as important as those steps might be. It's about understanding a) why executives don't care and b) why users don't care and then delivers something that resonates with them.

The book has no mention of organizational issues or ROI or search or SEO or even Google. In other words, the book provides valuable tips (of which there are many)  for developing and managing content unencumbered by management or users.

I've been reading books like this, along with companion white papers and presentations and sales pitches, for a quarter-century. For most of that time, I'd get excited about each new analysis, only to see another project founder on the rocks of executive apathy. I'm disappointed that we haven't advanced beyond these good books and toward solutions that executives want to deliver and people want to use.

---

Disclaimer: I received a copy of this book for review. I will donate my copy of the book. I was not compensated in any other way.

Monday, February 20, 2012

Page left blank

I thought that we were done with this.

For years, in technical manuals, we'd left a blank to make the pagination work out properly. Standards and conventions dictated that the first page of a chapter or section should be on a right-read page (recto). If the previous chapter ended on a right page, we'd need a filler.

Somewhere along the line, people got worried that someone would think that something had been left out of the manual. To make sure that we dealt with that hypothetical catastrophe, we started putting "This page intentionally left blank." on blank pages that were, thus, no longer blank.

Fast forward a couple of decades. Few people care that technical manuals have chapters starting on a right-read page.  We're also more conscious of dead trees.

I was wrong. Google Ngram, which scans books for occurrences of pa phrase or keywords, shows that we've been increasing our usage of this tree-killing practice.


So, I guess I should be surprised to find that UBS sent us a four-page Form 1099 with printing one side and this on the back:

UBS "This page intentionally left blank."

Blog Archive