Virtual Steve Comes to the Sun Microsystems Editorial Forum

One of my extracurricular activities is to chair the Sun Microsystems Editorial Forum. The Editorial Forum is a group of editors and writers who identify, discuss, and resolve editorial standards issues for the documentation groups across all of Sun. One of the primary responsibilities of the Editorial Forum is to develop and maintain the Sun Editorial Style Guide, from which both Read Me First! A Style Guide for the Computer Industry and the Documentation Style Guide for OpenSolaris are derived.

Earlier this week, I was pleased to welcome Steve Wilson to the Editorial Forum to continue a discussion that Steve started on his blog about how to move Sun's technical documentation into the new millennium. Steve's original discussion spawned further discussion on my blog and on the No Pen, No Ink blog. The idea for a meeting with the Editorial Forum came from Steve's suggestion to continue the discussion in a higher bandwidth medium than asynchronous text.

From the discussion, it seemed to me that Steve's ideas could be encapsulated in the following pieces of advice for writers:

  • Put your personality in your documentation.
  • Put your documentation in a blog.
  • Or better still, put your documentation in a video.
  • Let the power of search and aggregation organize your content for you.
  • Use your writing skills to become the center of new communities by providing quality information about quality products.

During the discussion, a range of opinions were expressed, some of which were in full agreement with this advice, others less so. I think that these differences of opinion are healthy, as they will help us find the mix of new and traditional forms of communication that will best suit Sun's diverse user base. I suspect that some of the time, we'll just have to “feel the fear and then just do it”, as part of finding out as we go along what works and what doesn't.

Put your personality in your documentation

Steve's discussion points:

Editorial licence alert: The links to the entries in Jonathan's Blog were not part of Steve's presentation. I added them myself because it struck me that Steve's ideas follow on from the points that Jonathan made.

Steve also suggested that to include personality in our publications, we should write in the first person.

My GBP0.02:

I am strong advocate of an active-voice, direct, and personal style in technical documentation. Throughout my career as a writer, I have been trained to write instructions in the second person because doing so makes the user the focus of attention and also makes clear who is doing what. For me personally, writing instructions in the second person would be a hard habit to break.

Put your documentation in a blog

Steve's discussion points:

From the discussion:

Instructions in blogs such as Geertjan's Weblog and Inside Scoop from the Tutorial Divas are often a rough early draft on that users can review by leaving comments on the blog. The blog postings are replaced when the content sediments down into more traditional forms of documentation.

Technical blogs by engineers (for example, Jeff Bonwick's Blog) provide useful source material for the documentation.

My GBP0.02:

Writing on the Aquarium blog about docs.sun.com at full speed, Alexis Moussine-Pouchkine echoed many of my own sentiments when he said:

While blogs are great and show up prominently while searching the Internet, some of them become obsolete and official documentation is really what should preempt other content.

Many of the arguments in Jakob Nielsen's alert-box column Write Articles, Not Blog Postings in favour of in-depth content apply to the information that we provide about how to use Sun products.

Or better still, put your documentation in a video

  • Users are now more comfortable reading online - even for extended periods.
  • Bigger pipes allows for richer content.
  • Rich content allows for more dense information transfer.
  • Rich content makes it more possible to transmit your personality.

Steve also suggested that with an inexpensive digital camera and the movie editing software that is available on most home computers, it's easy to create the type of rich content that transmits personality.

My GBP0.02:

These fine examples of how to transmit Sun product information with personality are a hard act to follow:

Let the power of search and aggregation organize your content for you

Steve's discussion points:

  • Every blog is an online magazine
  • Every blog entry is a piece of retargetable content
  • Feed aggregators cross promote content and allow for centralization
  • Where are you aggregating your content?

If the information is out on the web, search will find it.

From the discussion:

Cassatt provides instructions for replacing a motherboard on a blog in the May section of the What's New section of the Cassatt info central site. Obviously some customers will have that need in May, but many won't until later, perhaps December. Are they going to start doing multiple clicking to find their problem's solution that is no longer a What's New blog entry? Or will they go to Cassatt's Information Central to find persistent information? If users don't need to replace a motherboard now, why would they read an article under What's New when it is neither new or relevant to them at that time?

These comments in a Slashdot response to Jakob Nielsen's alert-box column Write Articles, Not Blog Postings suggest that some users require additional structure and organization of their content above what RSS feeds and search provide:

Blogs are nice for getting the news out and keeping up-to-date without having to sift through all documentation over and over again, but "official" blogs in particular also need to be condensed into a more structured form of documentation for when you can't or don't want to keep up-to-date and still need to find some information about a product/event/whatever. Search engines don't magically turn blog archives into usable documentation.
Bottom line: if these businesses really want to help people find the useful information, they should go back to maintaining a small number (ideally one!) of comprehensive, authoritative reference sites, and use blogs and newsfeeds as introductory material: highlight a useful new development or draw attention to a handy technique, direct the reader to the appropriate reference material if they want to know the details, and make sure the user never has to come back to that particular blog post again.
What I think is regrettable is that organisations with a lot of information to share about their products ? and Microsoft is just a single, high-profile example ? already seem to be giving up on maintaining high quality, comprehensive reference sites, as if the trend to allow staff to write their own blogs somehow provides an adequate replacement.

Use your writing skills to become the center of new communities by providing quality information about quality products

  • Personality isn't a substitute for good information.
  • Community isn't a substitute for good products.
  • All other things being equal:
    • People enjoy interacting with other people.
    • Information presented with personality is actively sought.
    • The product with the biggest community usually wins.
  • Writers are powerful.
  • Good writers, armed with new technology and tools can become the center of our new communities.

From the discussion:

Communicating in new forms leaves less time for traditional documentation. So, writers should try to reduce the amount of traditional documentation that is required by helping simplify the user interface (UI) of products. However, to influence the UI design of products, writers must be involved with engineering very early in the design phase.

New requirements imply new skills for writers, or maybe even new writers with different skills.

My GBP0.02:

What we write, how we write it, and how we deliver it are all determined by the audience and purpose of what we write. It's just basic technical writing practice really.

And finally

To paraphrase Lord Henry Wotton in Oscar Wilde's The Picture of Dorian Gray:

There is only one thing in the world worse than being talked about, and that is not being talked about.

So, I would like to thank Steve for talking about and talking to Sun's technical writing community. In my career as a technical writer, I have never before experienced such a level of interest from an engineering vice president in the work that the technical writing community does. Steve clearly sees value in the communication skills that technical writers bring to the party.

Comments:

[Trackback] This week I dropped in on the Sun Editorial forum.&nbsp; Paul Davies has a nice write-up .&nbsp; It's worth reading -- and I think Paul spent more time writing about it than I spent saying it!&nbsp; I've found it very interesting to have this ongoin...

Posted by Virtual Steve on July 20, 2007 at 02:46 PM PDT #

Thanks for distilling this discussion, which I wasn't able to make in person. Judging from my own use of blogs in areas outside of computers (music, photography, literature, art, politics), blogs are useful to find out what's going on, what people are doing, and what's newly cool. And, they point you to other places on the web that I might or might not find interesting. E.g. I like the content on person A's blog, and from their blogroll I can tell that they are reading person B (and C, and D, and ...), so maybe I should take a look at what those folks are saying too. (This cascades quickly into an avalanche, but if you apply restraint you can find some valuable information.) But I don't expect to find IN DEPTH information here. My hope is that if someone is saying "Look what I did with this new XYZ thingo", they will also include a link for more information about that thingo. In most cases I would never have known that this thingo even existed. (It's what we don't know we don't know that is most important to know.) So blogs "curate" information for us. If we find a channel of interest, maybe that can lead me to something I didn't know about but should know about. So blogs, in my understanding, don't replace in depth content, only illuminate it. And it's the blogger to tell us where to go next after they raise the subject. At least, that's what the GOOD BLOGGER must do. And their blogs are a treasure.

Posted by Richard Friedman on July 20, 2007 at 03:05 PM PDT #

Just to clarify. We (the tutorial divas) do not actually put actual tutorial drafts out. We put out material that we might turn into a tutorial. When we see some entries become widely accessed, we use that information to help us prioritize the tutorials we plan to write, or choose to include similar tutorial in a related tutorial.

When we post how-to information we keep it short and simple. We will post complex information if we see a need to get that information out fast, but then follow up with getting that information into a traditional document. If we were to turn the info into a full blown tutorial we will add a link to the blog entry, but we would never delete it as people do return to our entries over and over. If the information is obsolete, we try to update the entry with a note to that fact and point to more current information if possible.

I think I speak for both of us when I say that we do not think that all our tutorials should be posted to your blog. A well organized portal is a much better place for traditional docs, and traditional docs still play an important role in product adoption. The purpose of our blog is to connect with our readers on a more personal level, and to enhance the traditional deliverables, not replace them.

Enhancing usability to decrease the need for documentation should always be our goal. However, we can also minimize the traditional deliverables by eliminating redundant or unread/unnecessary documentation. Not only does this give us more time to focus on meeting our customers' needs through different, but more appropriate media, but it makes it easier for our customers to find the information by eliminating detritus that they have to weed through to find the gems.

Posted by Chris Kutler on July 21, 2007 at 05:38 AM PDT #

Oops, a typo. I meant to say "we do not think that all our tutorials should be posted to our blog." (not YOUR blog).

Posted by Chris Kutler on July 21, 2007 at 05:47 AM PDT #

That comment about the "replacing the motherboard" topic on the Info Central blog is certainly valid. In our case, putting that info in the blog was kind of a stop-gap way to get info out (in an afternoon) without formalizing it in an article or document. As a small team trying to cover a lot of territory, we thought that an acceptable solution, especially since blog entries are searchable on the Info Central site. My personal preference would have been to put this particular item in an online bulletin board, which is yet another type of community.

Posted by alan mcclellan on July 25, 2007 at 07:13 AM PDT #

Post a Comment:
Comments are closed for this entry.
About

pauldavies

Search

Archives
« February 2015
SunMonTueWedThuFriSat
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
       
       
Today
https://blogs.oracle.com/techscribe/entry/virtual_steve_comes_to_the
blogs.oracle.com
crawl=CC-MAIN-2015-11
40777
application/http; msgtype=response
sha1:5CBL42D66XVDC3I7V3DD25F6YP5HYVHF
<urn:uuid:fd2c5f81-5508-4c0e-8393-b1966503e529>
2015-02-28T16:43:55Z
23.6.22.140
sha1:LJYEYDKPKNKDTLW23MQQAD6I4NKXX2VO
<urn:uuid:2f4eb0a8-a41c-4a00-89d4-7e80d759a916>
https://blogs.oracle.com/techscribe/entry/virtual_steve_comes_to_the
response
<urn:uuid:99e55da5-76f8-4502-857c-d44c4872cc36>
robots: classic
hostname: ip-10-28-5-156.ec2.internal
software: Nutch 1.6 (CC)/CC WarcExport 1.0
isPartOf: CC-MAIN-2015-11
operator: CommonCrawl Admin
description: Wide crawl of the web with URLs provided by Blekko for February 2015
publisher: CommonCrawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf