The Identity Management Doc Summit...

...results are in and the Bats of Austin are out.

As previously blogged, I attended the Identity Management Doc Summit on the Sun campus in Austin, Texas last week. The summit was a way to bring stakeholders and writers together in order to come up with ideas for the future direction of the documentation for the Sun Java System Identity Management Suite. Writers present at the summit were those who work specifically on the products contained in (or downloadable for) the Suite including:

  • Access Manager
  • Federation Manager
  • Identity Manager
  • Directory Server Enterprise Edition
  • Policy Agents

Stakeholders present were training course developers, marketing persons, sales engineers, QA engineers, programmers, and the like. The Bats of Austin came out also.

Traditionally, our documentation has been task-based. An administrator of the product would use the Administration Guide and Administration Reference for information on console-based tasks and error messages, respectively. Deployment engineers would migrate to the Developer's Guide, Java API Reference, and C API Reference to integrate the product into an existing infrastructure. The issue with this type of document is that all the information is scattered. So, currently, I am writing the Sun Java System Federation Manager 7.5 Guide to Authentication. This book aggregates all information on the title subject and, with hope, will be the one-stop shop for your authentication needs. Will this title be a solution to the issue with task-based books? We're not sure as this is a first attempt. And with the advent of blogs, wikis, digital demos, open source, and the like, maybe there's a new way to dole out information we haven't thought of yet. So, with everyone together, we discussed where we should take our docs in the future.

The morning session was a bunch of presentations to introduce the participants, explain the products and the suite, and map out the afternoon session. Brandon Whichard is Product Manager for Sun Java System Identity Manager. One slide from his presentation, in particular, caught my eye. It detailed the key persons who he felt read the documentation. They are listed below with the type of information they generally look for:
  • Sales Engineers
    • What does it do?
    • What platforms does it run on?
    • Feature details
    • How do I complete a Proof Of Concept?
  • Professional Services Engineer/Deploy Engineer
    • How do I deploy successfully?
    • Best Practices
    • Gotchas - what to avoid
  • Product Administrators/Customer Administrators
    • Common error messages
    • Routine maintenance
    • General use
    • Troubleshooting

Additionally, in the morning, we spoke of new ways that companies were using to impart their information. Wikis, demos, YouTube, deployment examples, and podcasts were just a few of the methods discussed. The Bats said nothing.

In the afternoon session, everyone was asked to write on post-it notes the things we could do (or were doing now) to improve our documentation and help customers find the information they need. For example, two of the ones I wrote were:

Instead of YouTube, use SunTube, if there were one


Wikis - too open? Need limited access wikis?

All post-its were then divided into categories and the summit participants were divided into groups. We each were given a few categories and, among the grooups, were asked to whittle down the post-its to the five best suggestions. Following our whittle, we took the best seven from all the groups and plan to use them going forward. Following are whiteboard shots of the top five from each group. The first is a shot of the five best from my group. I put this one first because it's the only picture that also contains all our post-it suggestions plus the five we chose. The numbers in parentheses reflect the number of post-its we had that mentioned that item. One interesting note about our grouping was that six post-its mentioned printed books. Most of us thought that a bit odd and agreed that it shouldn't be in the top five but it was there nonetheless.

The second of four groups came up with the following five suggestions. I felt these were really job requirements for a technical writer and not necessarily new ways of imparting information. Common Criteria, though, we should pay more attention to if we want to sell to government agencies.

The third group came up with the following. I am in complete agreement with number one although I am not sure what incentives are relevant to number 5. I'd like an iPod myself...and so would the Bats.

The final group had the following. Number three means to keep up with the competition's docs by perusing their version of and scamming ideas. Number five is, unfortunately, always an issue.

Following are the top seven decided by everyone:

Tied for 1st Place:
  • Writers should experience more user interactions; doc should reflect hands-on experience
  • Deployment examples
Tied for 2nd Place:
  • Complete, accurate, relevant documentation (isn't this part of a technical writer's job?)
  • Tutorials (videos, etc.)
Tied for 3rd Place:
  • Aggregation and organization (See first picture above)
  • "______pedias" Content developed and deliverd a la Wikipedia
  • Designate a Content Steward to monitor info that gets published, and makes it easier for customers to find/access the information
  • Scenario-based documentation (case studies, sizing guides, etc.)

A few other things that came out:

Oh yeah...the Bats of Austin came out too. I, fortunately, had a chance to go downtown Austin and check out some of this beautiful city. My friend Kathryn took me to see the Bats of Austin who leave their perch underneath a downtown underpass every night at dusk. And now you can see them from the comfort of your chair.

The bats reminded me of the fairy penguins that come out of the sea each night on Phillip Island.

In conclusion, I felt the summit was time well spent and a success all around. Thanks to Mark Craig for putting it together. (I could say something about Stephen Sondheim here but this post is long enough.)


Thanks for putting this all together in your blog.

John D.

Posted by John Domenichini on May 01, 2007 at 02:39 AM PDT #

Wikis - too open?
Too open? I don't understand ;-)

Posted by Pat Patterson on May 10, 2007 at 01:50 PM PDT #

Wikipedia is considered 'too open' as anyone can change anything. Truth and lies can be added. Anyone can add information to doc wikis (supported, unsupported, wrong, right). Is that to open?

Posted by DocTeger on May 14, 2007 at 06:58 AM PDT #


Thanks for recapping your docs summit. Your results are very similar to what the Comms writers have experienced and what we feel that our customers want from our documention.

However, what I'd like to see more of is how we get there. Back in 2005 (that long ago?), the Comms writers had a summit that came up with these goals, which we called a new strategic model for documentation (catchy, eh?):

  1. Creating a vertical channel for Communications Suite information
  2. Implementing Rapid Task Analysis (RTA) (and later, Extended Process Analysis--EPA) into our documentation process
  3. Forming Advisory Boards for Support (internal), Customers, and Partners
  4. Providing more support-readiness information and tools in the form of deploy examples, tech notes, FAQs, downloads, etc.
  5. Issuing requirements for long-term solution

Looking this list over, Comms writers have executed on some items, put some thought into others, and have fallen short on one.

We have created our vertical channel, that is, Comms Hub; we conducted an initial round of RTA/EPA training (our boss is presenting this at an internal brown bag this week, if you're interested); and we have issued requirements for a long-term solution that would enable customers to build custom documentation. (Indeed, one of our writers is working on code name 'Doctopus' right now.) In terms of more support readiness docs (deploy examples, faqs, case studies, articles, blogs, and the like) we are getting better, but the obstacle here is primarily resources, both on the pubs' end and on the SMEs' end. However, by using blogs and BigAdmin articles (for example), we're finding that we can get information out quicker to our customer's hands than through the older DSC repository. re: advisory boards, which I think are a great idea, we just haven't got the momentum going yet to make this happen.

My point is that we should be formulating tactical (Hub, blogs) and strategic (RTA/EPA, customizable docs) ideas to better our docs. And continually evaluating these ideas as we go forward.

Thanks again for sharing your doc summit!

Posted by Joe Sciallo on May 15, 2007 at 04:48 AM PDT #

Post a Comment:
Comments are closed for this entry.



« June 2016