Virtual Steve : Weblog

Comments:

A video is only worth 1000 pictures if it's 33.3 seconds long, assuming 30 frames/sec. :-)

Posted by Kevin on June 21, 2007 at 02:59 PM PDT #

To answer your suggestions in order

Some members of the IPG have already been thinking about blogs instead of books.
Not for blind people.
Not for blind people.
And a further thought: Any technical writers lately asked your engineers to think about, say, scripting instead of C?
Posted by Paul Davies on June 21, 2007 at 05:56 PM PDT #

Hi Paul. Thanks for your comments. They're true, and I never implied no one in IPG was thinking about this stuff, just that I wanted MORE! As for your other comments, I don't think you can make an excuse that not everyone can/will use a new medium so we should ignore it. And BTW, at the meeting the writers didn't volunteer suggestions on which programming language we should use, but they did offer to help us design the product's user interface. I signed 'em up.

Posted by Steve Wilson on June 21, 2007 at 08:57 PM PDT #

Steve, You're welcome, and many thanks for the opportunity to converse with you about topics that we both feel are important.

I didn't intend to suggest that we should not take advantage of new media. I realize now that I had sacrificed clarity in the interests of brevity. Rather, I just wanted to make the point that even as we embrace the exciting possibilities afforded by new media, we must not abandon those who, for one reason or another, are unable to share the benefits of these new media.

Great too to hear that you signed up the writers to help with the deesign of the product's UI. I have had the good fortune to cooperate with the engineers on UI design on previous projects and the result has been a win-win: greater ease of use for the users and less documentation for me to write:-)

This exchange has inspired me to discuss these topics in more depth on my own blog.

Best regards.

Posted by Paul Davies on June 22, 2007 at 05:54 PM PDT #

Steve: I'm interested to read this request that Sun documentation be delivered in more friendly, informal, bite-sized pieces of information, which I've heard has come from other areas as well. I know some customers who are already frustrated at having to go to several different places for information (docs.sun.com, SunSolve, BigAdmin, forums, etc.) and would much prefer to have information in one reliable, searchable, organized place in a consistent format. The feedback I hear is that if the engineering of DSC was better, customers would be perfectly happy with that format of information delivery. I was just wondering where the push is coming from for blogs, forums, articles, videos, etc. for the delivery of product information. Is there any Sun customer research that is accessible? Thanks!

Posted by Janice Gelb on June 25, 2007 at 05:12 AM PDT #

Hi Janice. I don't think I want to suggest that we put docs more places. I want to suggest that we spend a higher portion of our writers' time being involved in different kinds of activities (vs. simply producing more docs). I think there is general agreement that we need some type of traditional "docs", but most also agree that they're a place of last resort for people. Few people start to learn products by just popping open the docs and reading. However, lots of people now read blogs by their favorite "personalities" related to the products they use to learn more about the current state of the art. Check out Romen's Blog or Geertjan's Blog about NetBeans as examples. Almost every day people who use NetBeans can go to one of those places and learn something new about their favorite IDE. It's things like this around which you can build communities. Docs.sun.com isn't designed to be a community center.

Posted by Steve Wilson on June 25, 2007 at 08:40 AM PDT #

"I want to suggest that we spend a higher portion of our writers' time being involved in different kinds of activities (vs. simply producing more docs)."

Hmmm. Seeing that the Sun Cluster writers are allocated 119.09% of their time to complete the Sun Cluster 3.2u1 documentation by the release date, and seeing that I'm personally short by 3.34 weeks for Sun Cluster 3.2u1 documentation, and seeing that over half of the Sun Cluster documentation staff was laid off or reassigned last August, it appears that I'll be spending all of my time as well as some of my own "personal" time "simply producing more docs" for Sun Cluster 3.2u1. I simply won't have the time to "put myself on YouTube". Sorry. :(

If you want to "challenge" us to put ourselves on YouTube or to blog or to build community, then give us more resources, more qualified technical authors, and consequently more time to do that. The Sun Cluster writers gladly welcome any assistance from you or your staff in developing content for Sun Cluster 3.2u1 to enable us to put ourselves on YouTube, to blog, and to interact with the community.

Talk is cheap.

Posted by TechDogg on June 25, 2007 at 10:56 AM PDT #

TechDogg. Thanks for joining the conversation. I can't speak to the specifics of what you're doing on Sun Cluster, but 119.09% does sound like you're quite busy.

I can tell you that for SysNet's products (Sun Connection, N1, and Sun MC) I am putting my money where my mouth is. I've asked the IPG team supporting those products to focus more of their efforts on getting information out through these "new media" channels and to put less effort into manuals than they have in the past. It's a trade, but I think it's worth it. The good news is it's starting to pay off in some really interesting ways (cool screen casts, blogs, etc) and I'm looking to see the team do even more of it in the future. I think our customers will appreciate it too and we'll have more of them in the future as a result.

Posted by Steve Wilson on June 25, 2007 at 11:26 AM PDT #

Steve:

It's things like this around which you can build communities. Docs.sun.com isn't designed to be a community center.

I agree. However, where we disagree is whether a community center is the best way to deliver comprehensive and usable product documentation to our users. There's a big difference between cool new uses for products being mentioned in a blog and having a blog entry be the only documentation of that product usage.

I've asked the IPG team supporting those products to focus more of their efforts on getting information out through these "new media" channels and to put less effort into manuals than they have in the past. It's a trade, but I think it's worth it. The good news is it's starting to pay off in some really interesting ways (cool screen casts, blogs, etc) and I'm looking to see the team do even more of it in the future.

Writing for these new formats is not simply a matter of just deciding to write cool snappy articles and film nifty videos. A lot of research and planning is needed in order to figure out how to technically deliver and archive such information, and how best to write for it. As TechDogg noted, writers and production staff barely have enough time to deliver standard product information let alone the time and resources to devote to completely changing how information is delivered, or writing supplemental articles or blogs on the side.

Asking writers to put less time into comprehensive product documentation and more time into new delivery mechanisms means that the documentation is going to suffer. Unless, as TechDogg mentioned, the management that is pushing for additional product documentation in new formats also commits to provide the resources to accommodate the extra research required to deliver this information, and to ensure that customers can retrieve the information they need.

I think our customers will appreciate it too and we'll have more of them in the future as a result.

You never answered my original request about customer research. You think that our customers will appreciate it too. But is there any research to suggest that our customers are asking for this type of information delivery?

Everyone likes cool new toys, our customers included. If someone says to a customer "Do you like blogs?" they're probably going to answer in the affirmative. But are customers being asked the follow-up questions: Whether they want some product documentation delivered only in blogs? Or whether they want product features documented in several different places and in different formats?

Imho, the drain on IPG time and resources to deliver product information in new and scattered formats is not justified unless customers are actually pushing us to deliver information in other ways, not if they're being pulled in that direction by Sun representatives.

Posted by Janice Gelb on June 25, 2007 at 03:28 PM PDT #

Just a minor clarification on someting in one of Steve's comments: When I admitted on my own blog to never reading documentation except in desperation, I meant as an alternative to trial and (especially) error with the product. In this context, documentation that I never read except in desperation would include blogs and screencasts as well as more traditional forms of documentation.

Posted by 192.18.43.225 on June 25, 2007 at 03:40 PM PDT #

@Janice
> You never answered my original request about customer research.
I don't have formal research on this, but I talk to customers every week about their technology decision making patterns. They don't express specific preference for blogs or for manuals, but their choices make their preferences very clear. I've had a number of recent meetings with startup companies about how they choose their development and deployment environments. The universal answer is that they found a support community that made the choice easy. For example, a number of start ups I've met with have choosen Debian Linux as their OS deployment. This is an environment that doesn't even have formal documentation, but it does have an active, self-supporting community that makes it easy for people to get started and stay informed. For a similar example inside Sun, you can look at NetBeans. NetBeans has little in the way of formal manuals, but has an active community that makes it easy for people to get started. The tools group made a choice some time ago to focus more of their efforts on community.

I think the folks in IPG have the skills and are perfectly positioned to be at the heart of these new communities we need to built around our products. As the produt owner for SysNet's technologies, I've agreed to make the trade to have the writers on those products spend more time on community and new media. Those of you that work on Solaris, Cluster or other products might be surprised at the answer you'd get from Jeff Jackson if you asked him if you should spend more of your time to get involved in these communities. I've known Jeff for a long time, and he's a big proponent of this stuff. OpenSolaris (the community) is critically important to Sun.

One other note, lest people think I have some inherent objection to information in book form. In 2000 I did write a book. It was a hugely rewarding experience, but it did form a lot of my opinions on the subject we're discussing here. The book took twelve months to produce and when it came out it was state of the art. It got a great reception when we introduced it at JavaOne. However, 18 months later it was already showing major signs of wear. The shelf life on this kind of technical information can be very short. That's just one of the many reasons I've been pushing this way.

Posted by Steve Wilson on June 25, 2007 at 09:48 PM PDT #

"TechDogg. Thanks for joining the conversation. I can't speak to the specifics of what you're doing on Sun Cluster, but 119.09% does sound like you're quite busy. I can tell you that for SysNet's products (Sun Connection, N1, and Sun MC) I am putting my money where my mouth is. I've asked the IPG team supporting those products to focus more of their efforts on getting information out through these "new media" channels and to put less effort into manuals than they have in the past. It's a trade, but I think it's worth it. The good news is it's starting to pay off in some really interesting ways (cool screen casts, blogs, etc) and I'm looking to see the team do even more of it in the future. I think our customers will appreciate it too and we'll have more of them in the future as a result."

And based on what I hear, your documentation team is as overbooked as the Sun Cluster writers are, and, as a result, faced with making the same decision: books over blogs.

"I've had a number of recent meetings with startup companies about how they choose their development and deployment environments. The universal answer is that they found a support community that made the choice easy. For example, a number of start ups I've met with have choosen Debian Linux as their OS deployment. This is an environment that doesn't even have formal documentation, but it does have an active, self-supporting community that makes it easy for people to get started and stay informed."

Two key phrases here: "startup companies" and "Debian Linux". Translation: FREE. That's pretty much why startup companies prefer and choose Debian Linux. It's all they can afford. I doubt it has anything to do with the fact that an "active, self-supporting community" is available.

Posted by Tech Dogg on June 26, 2007 at 05:41 PM PDT #

@techdogg
Two key phrases here: "startup companies" and "Debian Linux". Translation: FREE. That's pretty much why startup companies prefer and choose Debian Linux. It's all they can afford. I doubt it has anything to do with the fact that an "active, self-supporting community" is available.
Solaris is just as free as any version of Linux. Pick your favorite version of Solaris 10, or Solaris Express and start developing and even more to deployment. You don't have to pay Sun anything (although you may choose to pay us for support). People have many choices for zero cost products, and they're choosing between them based on community. It's the leading factor in discussion after discussion. We can only ignore that at our own peril.
Posted by Steve Wilson on June 27, 2007 at 06:04 AM PDT #

Steve, I have to disagree with you when you say "that they're [docs] a place of last resort for people." As a developer, I strongly disagree with that. I need detailed information when I'm integrating a product using an API or setting up a complex system with lots of options and configuration parameters. I also need books when I'm offline (which is more often than you might think). For me, docs are the *first* place that I look, and I know many other developers who feel that way too. Now of course, that's not true for everyone, or maybe even the majority. So, what I see as important is that we need to offer as many types of information as possible. And, we need to be able to create that content efficiently by taking content that was written for one delivery medium and repurposing it for another medium. The reason that you don't hear much about books is because people are generally satisfied with them. If you take the books away, people are going to complain. It seems to me that you are concerned more about *advocacy* of technology rather that documenting it. For Sun Connection, advocacy over documentation make sense. The product isn't hard to use, so it doesn't require extensive (dare I say any?) documentation. In fact, I would actually classify Sun Connection as service rather than a product. If advocacy is your goal, then blogs and articles are definitely superior to books. No question. But every product is different. So, what works for Sun Connection isn't necessarily going work for a complicated product. Thanks for the thread. It's really interesting to read.
Posted by Steve Cogorno on June 27, 2007 at 11:53 AM PDT #

I don't have formal research on this, but I talk to customers every week about their technology decision making patterns. They don't express specific preference for blogs or for manuals, but their choices make their preferences very clear.

Perhaps you're talking to customers about how they're choosing products and I'm talking to the customers one level down who have to *use* the products :-> The feedback I get is that when customers want product information, they want to be able to go to a known location, find the information easily, and have the information be comprehensive and accurate. They don't care how friendly it is or whether it comes in a snazzy up-to-the minute format.

FYI, I have direct feedback about the Sun Connection area on SunSolve from a very experienced customer with a large installation and numerous Sun Connection licenses. He says he finds the community approach for support has major shortcomings because while some questions are answered, others get a response either of "Interesting, we'll get back to you" or no response at all (and often the first group never gets the promised response). He says that without actual documentation to refer to, he can't research the question himself and if the community doesn't respond to the question, he's stuck and sometimes has to resort to filing a support ticket, which is time-consuming for him and costs Sun time and money. Also, the forum approach means that answers have to be customized every time. Finally, he says that the signal-to-noise ratio is offputting, because you have to wade through other people's questions and low-level problems that might easily be answered in traditional documentation.

He also has a problem with the BigAdmin information area due to a lack of structure, which makes it difficult to find specific information that might be useful to him.

I want to say yet again that I am not trying to argue against the importance of informal communication or community interaction. They're certainly valuable and help customers feel more invested in a product and a company. What I am trying to say is that the type of information that is delivered in that kind of informal environment is not comprehensive enough for the customers who have to use our products in an in-depth way.

However, 18 months later it was already showing major signs of wear. The shelf life on this kind of technical information can be very short. That's just one of the many reasons I've been pushing this way.

I certainly agree that with the more rapid turnaround in product delivery, we need to investigate ways to make more efficient use of our documentation delivery schemes. As Steve mentioned, multiple reuse of common information is one direction we are investigating.

As the product owner for SysNet's technologies, I've agreed to make the trade to have the writers on those products spend more time on community and new media.

Could you be a bit more specific about how you see this playing out? Given that we are still producing traditional product documentation, how exactly are you picturing having writers spend more time in community communication and less on the documentation? What parts of the documentation effort do you see as expendable and how are we going to communicate the reduced documentation scheme to our customers?

Posted by Janice Gelb on June 27, 2007 at 03:53 PM PDT #

All. Thanks to everyone who contributed to the discussion. I think it's a really important one for Sun as we learn to balance our traditional docs approach with new media. If any of the Sun folks wants to continue the discussion in a higher bandwidth medium than asynchronous text just let me know. I'd be happy to talk in person or on the phone.
One thing I will note is the very existence of this discussion says something about the power of this medium. It's been very interesting!
Posted by Steve Wilson on June 27, 2007 at 08:39 PM PDT #