Factotum: Documentation Handyman

Let's face it, searching for information on the Net is a common fact of every day life now, especially if you're involved with deploying and supporting technology like Communications Suite. So, where do you start, should you just google and hope for decent results?

To begin with, here's a comprehensive list of sites that contain Communications Suite information:

• New Comms 6 Information: The upcoming Comms Suite wiki on wikis.sun.com
• Comms 5 documentation: http://docs.sun.com/app/docs/coll/1634.1
• Comms 5 docs, PDF download: http://www.sun.com/bigadmin/hubs/comms/files/COMMS5_DOCS.zip
  
• Messaging Server FAQ and reference: http://msg.wikidoc.info/index.php/Main_Page
• Comms Hub: http://www.sun.com/bigadmin/hubs/comms/
• Comms tech articles and white papers: http://www.sun.com/bigadmin/hubs/comms/library/techarticles.jsp
  
• Comms Software Forums, email aliases: http://forum.java.sun.com/category.jspa?categoryID=57
• Blogs: http://blogs.sun.com/factotum,http://blogs.sun.com/jhawk
• Email aliases, such as Info-IMS@arnold.com
  

Each of these sites has its own local search mechanism that you could use. But what if you're interested in globally searching all these sites? To start with, Sun provides its onesearch engine, that searches across all Sun sites, including blogs, forums, and wikis. Here's a sample onesearch on "installing messaging server 6.3:"

While promising, Sun's onesearch doesn't include non-Sun sites. To address this short coming, we've set up a couple of Google Coop search engines. Google Coop enables you to build your own customized list of sites upon which to google. Here are the coops that we are experimenting with:
» Go to the Messaging Server 6.3 Google Coop Search Engine
» Go to the Communications Suite Google Coop Search Engine

Knowing what sites to look at, and how to search them, should help you begin to get a handle on finding the Comms Suite information that you are looking for. Have a favorite search trick or tip? Please drop us a line and let us know.

A reader of the document titled Deployment Example: Sun Java Communications Suite 5 on a Single Host let us know recently of a potential problem. To quote:

In the document 'Deployment Example: Sun Java Communications Suite 5 on a Single Host', there was an important prerequisite missing: The installer must have their umask set to permissive (umask 022). Mine was set to 077 and it caused several directories and files to get the wrong permissions, causing some of the steps to fail.

Passing along to the community, as I know this doc is used very often.

A Comms deployment gives a big thumbs up to ZFS. And if you missed the ZFS announcement for Messaging Server 6.3, here it is again.

We've been talking internally about putting together a page of useful Communications Suite tools to help you better manage your Comms deployments. It will be a while before we get this page (site, wiki, whatever) off the ground, but in the meantime, the discussion got me thinking about searching for Comms Suite information. Sure, we all use Google, but how many of us are using Google coop, which enables you to construct customized web searches of only the sites you want?

Here are two Google coop examples that Sun employees have thrown together:

• Sun Java System Messaging Server 6.3 Search Engine, which searches for information on the current Messaging Server release. (This would be an example of a fairly targetted coop.)
• Communications Suite Search Engine, which searches for information for all Comms products for all releases. (This would be an example of a fairly broad google coop, at least for Comms products.)

What really rocks with Google coop is the ability to tweak your searches, adding or subtracting sites over time, to finetune what you are looking for.

You can also use Sun's onesearch, to search across all Sun sites, including forums, blogs, and wikis. Here's a sample onesearch on "installing messaging server 6.3:"

Whatever your search engine choice, it's obvious customers rely on searching as the primary means of obtaining information. And we need to keep this in mind as we move forwards with newer documentation efforts, such as the Comms Doc Wiki, which we are cooking up for the next release.

From an email I received from BigAdmin recently, a list of recently published articles that the Comms community might find useful:

• Sun Java System Messaging Server Message Store Disaster Recovery Techniques
• Sun Gathering Debug Data for Sun Connection
• Configuring Sun Java System Messaging Server Log File Rotation
• Installing and Configuring Sun Java System Portal Server 7.1 Update 1 Blog Portlet
• Adding Sun Java System Portal Server 7.1 Community Services to Your Portal
• Switching Databases From MySQL to PostgreSQL 8.2
• Sun Java System Directory Server 6.0 as an LDAP Naming Service: Part 1 -- Installation and Configuration
• Sun Java System Directory Server 6.0 as an LDAP Naming Service: Part 2 -- Client Configurations for the Solaris OS
• Sun Java System Directory Server 6.0 as an LDAP Naming Service: Part 3 -- Client Configurations for Red Hat Linux and AIX
• Sun Java System Directory Server 6.0 as an LDAP Naming Service: Part 4-- Post-Configuration Tasks
• Diskless Setup for the Solaris OS for x86 Platforms

Continuing some thoughts on my previous threads (here and here) regarding the state of Communications Suite documentation, what if the Communications Suite docs were made available in wiki form, and you the community could lend your expertise to contribute to those docs, making them even better? Sound like a pipe dream? Well, as it turns out, there is at least one group at Sun doing just that right now. Have a look at how OpenDS is managing its documentation in wiki form. I think you'll be very surprised and pleased.

If such a move to wiki-based information were made for a product, my initial questions would be:

• Could you live without having information in PDF books?
• Could you accept some information that was labeled "work-in-progress?"
• Could you manage to deal with legacy information in multiple sources/sites, for example, new information delivered via wiki, and legacy information on docs.sun.com?

As usual, feel free to comment or drop me a line.

We probably haven't done as good a job on communicating this to the world as we should have, but right now, you can migrate from other email vendors and groupware services (Microsoft Exchange, Lotus Notes, Novell, and Critical Path come to mind) to Sun Java Communications Suite and Messaging Server.

Some news on this front as well: GSS just announced that they can help customers switch from Lotus Notes and Domino to Comms Suite when they are using Microsoft Outlook as a client. And GGS is a Principal ISV Partner. Read the entire announcement from GSS.

Old news, but still good: Sun provides the Sun Groupware Migration Toolkit for such migrations as well. Indeed, I believe Telstra recently successfully used it in their migration. Read more about SGMT.

Sun partners can also learn more about SGMT from our ShareSpace site.

Re: my post from Monday, how would the Comms Community like a wiki-based documentation solution apropos of what OpenDS is providing on its wiki doc site? Evidentally, this is "the" documentation site; all the information normally found on a product doc repository, such as our docs.sun.com, is instead located on this wiki.

I see a lot of advantages to this model, including: community contribution/participation; more timely doc updates; ability to find out better what information matters most to customers; and so forth.

Artwork from Avatar Press

Hypothetical question to the Comms world. What if we were working on a new product and you had a chance to influence the kinds of information you needed to successfully plan for, install, configure, administer, and use said product. Would you be willing to share your thoughts, contribute ideas, and give us feedback on our plans? Again, this is strictly hypothetical.

There are of course, many ways to look at this. For example, you might suggest or rank traditional publication manuals, aka:

• Deployment Planning Guide
• Installation Guide
• Release Notes
• Administration Guide
• Configuration Guide
• Customization Guide
• Online Help
• etc.

Then again, since we are seriously thinking (hypothetically, 'natch) of potentially doing something very different in the doc space, rather than lock you in to the above traditional mentallity (which is just fine on its own), it would be nice to have thoughts and feedback on the other types of information and delivery sites that we currently provide, such as

• Comms Suite Hub
• Wikis, such as http://msg.wikidoc.info/index.php/Main_Page
• Tech Articles and Notes
• Blogs, like Factotum and Jhawk
• docs.sun.com

as well as comments about Star Trek-like ideas, such as dynamically-generated documentation.

If your interest is piqued, feel free to drop a line or use the Comments section below to brainstorm.

Update 1:

One of my co-workers suggested, and rightly so, that a question such as, "If there's one thing you'd really like to see in the docs, that would really help you do your job better, what would it be?" would also be helpful. Conversely, you might also have the question, "What's been the most frustrating part of the docs?" If you find either of these questions pertinent to this endeavor, feel free to use them.

In case you're wondering, here's the place to start looking for Communications Suite 5 patches:

http://www.sun.com/bigadmin/hubs/comms/downloads/updates.jsp

I'll be attempting to keep this page as up-to-date as possible. In fact, I made a few updates this week.

Though I write specifically about Communications Suite products, it's clear that there's a general trend across Sun and the computing industry itself: Technical information gets served in a variety of ways nowadays. Not just limited to the traditional fare of product manuals, you can also have your info served up by email aliases, forums, technical articles, blogs, and wikis, to name a few. And where once the documentation chef was primarily the 'technical writer,' we're finding many cooks with all kinds of backgrounds stirring the info broth, forcing the technical writer to become more of an information manager than just the producer of books.

We in Communications Suite recognize that this new information landscape brings with it a certain confusion and Wild West atmosphere to what used to be a fairly calm endeavor (just go to the product docs repository (aka docs.sun.com) to find (if you can) the info that you are looking for.

My take is that publishing more information rather than less--especially when we recognize there are gaps in the product docs--is a good thing. Is this a problem? In general, I don't think so. I believe that the Comms community realizes that publishing venues such as blogs and wikis might not carry the same kind of sanctified stamp that a manual or an article carries, but the information is welcome nonetheless. An additional boon for customers: with these tools such as wikis and blogs, we no longer operate under the excuse of, well, it's too hard to push out new information to DSC between software releases. We can operate more in a continuous info release mode.

I also think that by putting information out in these less-official channels gives customers the chance to work on and solve problems as they arise, and to give the folks at Sun a chance to receive more feedback on where we can improve our information delivery efforts. And, where appropriate, we can fold in information from a wiki or a blog into the product docs, to give that information an official home and hopefully make it easier to retrieve in the future.

One valid complaint: how do I keep track of all this information from release to release? To help solve this issue, at least with tech articles and notes, you should refer to the Comms Hub Technical Articles tab, which now provides a complete historical listing of all our tech notes and articles. Part of my duties is to keep this index current and up to date.

Are we in the midst of a documentation/information revolution? From where I sit, in Tech Pubs, I'd say yeah, but it's a revolution that's still forming without any one clear leading movement. My hope is that customers will tell us more and more what works and what doesn't work--that is, we'll let the community drive adoption of the tools that are best at solving customer information needs.

Sun throws its weight behind SyncML.

Looking back through my email this week, here are a couple of things that I'd like to pass along to the Comms community:

• Another week, and still no official statement supporting ZFS. But stay tuned, it's getting close.
• Doc error in the Communications Express 6.3 Administration Guide, where it says, for the uwc-user-attr-icsExtendedUserPrefs-ceNotifyEnable attribute:

  Specifies whether to send email messages (containing ical attachments) to internal invitees when new events are created. Valid values are: false, true. By default, uwc-user-attr-icsExtendedUserPrefs-ceNotifyEnable is set to "1" (true).

  It appears that in this case, the attachment is not sent with the email, but this is not a feature bug, but rather, a doc mistake. Per the expert:

  This setting enables the Notification feature for a user in the server. In the server if Notification is enabled, an email is sent to that address when an invitation is placed in the user's calendar. It is just a notification of the invitation in the calendar and not the invitation itself. So no ical attachments are sent. ical attachments are sent only to external invitees or internal invitees who have not given invite permission to their calendar. Such invitations have nothing to do with the ceNotifyEnable setting.

• In Messaging Server, to remove messages (imexpire command) placed in some sort of junk folder based on how long they have been in the folder (say you want to get rid of messages that are older than 100 days), you need to use the savedays attribute, which was added in a patch. See the Messaging Server 6.3 Administration Guide for more details: http://docs.sun.com/app/docs/doc/819-4428/6n6j4267s?a=view

  Note: Use the store.expirerule file to configure expire rules with the new attributes.

• Another doc issue with configuring Calendar Server 6.3 and SSL. From our expert:

  I successfully configured Calendar Server 6.3 in SSL mode,
  but there is a documentation error with the Calendar Server 6.3 Administration Guide.
  
  The certutil -f  command mentioned in the
  Administration Guide expects the password as a single
  word in the passwordfile itself.
  
  The example in the doc states:
  - - -
  The format of password file entry is as follows:
  Internal (Software) Token: password
  - - -
  
  Instead of "Internal (Software) Token: password" you
  use something like "password1234".
  - - -
  
    NOTE:
    You can also use the certutil command without the -f option and
    enter a password, which puts this password into the
    sslpassword.conf file as well.
  

• Log rotation in Communications Express: For Communications Express 6.3, you use the uwc.log.maxsize and uwc.log.maxfiles properties to configure log rotation. To have the same functionality in Communications Express 6.2 (Java ES 2005Q4), you need patch 118540-41.

Nothing too hair-raising, just a few bits of Comms-related information to start the week.

• New: Installing and Configuring Sun Java System Calendar Server 6.3 With Sun Cluster 3.1 Software
• Revised: Sun GDD for Messaging Server doc. The dbhang command has been updated.
• Announced: We have completed testing Messaging Server 6.3 and Sun Cluster 3.2 software, and are announcing support for this combination.

Messaging Server Support Field of Dreams?