Thursday Jan 31, 2013

New Blog: Oracle Communications Documentation and Curriculum

My manager and other members of the team have started a new blog--the Oracle Communications Documentation and Curriculum blog-- to talk about content creation and getting some real-world feedback to help improve that content. Check it out when you get the chance.

Friday Jan 25, 2013

Unified Communications Suite: Wiki Documentation Changes

As longtime UCS-ers know, we have been providing wiki docs for many years now. One of the benefits of wiki docs is that writers can and do update content more frequently than with a static documentation environment. While this means that documentation issues get addressed more readily, it could also present a small problem in knowing when a doc (aka wiki page) has been updated. In addition, you might want to know not only that the page changed but how can you easily spot that change? Was the change cosmetic or substantive? And so on.

In the interest of making this knowledge a bit easier to come by, and to highlight the continuing work that the UCS InfoDev team is putting into our documentation, here are a few ways in which you can determine when a doc has been updated:

    • Look at the page history.
      On any page, from the Tools menu, select Page History. You then see a list of versions, dates, who made the change, and (hopefully) a comment on what was changed. For example, here is the page history for the Calendar Server 7 Administration Guide.
    • Once you are on the Page History page, you can compare versions. Click the check boxes beside the versions you want to compare then click the Compare selected versions button.
    • A quick and easy way to see what pages have changed recently is to choose Pages from the Browse menu, then select Recently Updated. You see a list of recently changed pages for the entire wiki space. This list is convenient in that you also get a view change link that takes you to a Page Comparison page, showing the changes.
    • If you have a standard Oracle ID, you can "watch" a page and be automatically notified by email when a change occurs.
      To watch a page:
      1. Log in to
      2. Go to the page that you want to watch.
      3. Click the Tools drop down menu and select Watch.
        When we make a change to the page, sends you an email.
    So there you have it. You now have all the info you need to stay up-to-date on our CommSuite wiki changes.

      Friday Jan 18, 2013

      Communications Suite Documentation: Wiki Structure

      From time to time, I get questions on how to find a particular piece of documentation on the Unified Communications Suite documentation wiki. So I thought it would be useful to give an explanation of our wiki structure and how to approach, at least on one basic level, looking for a particular document.

      In a nutshell, we have structured the Communications Suite documentation into two information buckets: "release-specific" content (Release Notes, New Features (formerly What's New), Installation Guides, and Upgrade Guides); and "non-release specific" content (Administration Guides, Developer Guides, Customization Guides, Tuning Guides, and the like). Release-specific content is always located on its own wiki space (in effect, its own web site), whereas the non-release specific content is always on the same "home" wiki space. In terms of URLs, what you have is this:

      Non-release Specific Content
      Release Specific Content
      and so on...

      Thus, for each new Communications Suite release, such as Communications Suite 7 Update 2, we publish the aforementioned release-specific content on its own wiki space. The thought here is that customers appreciate having everything they need to install or upgrade a particular release in one location, and don't have to click around to get what they need. Nor do they want to be encumbered by other extraneous content that only gets in the way of the installation or upgrade process.

      Notice that the release specific content URLs follow the naming convention CommSuite<v>U<n>, where <v> is the major version and <n> is the update. So knowing that, if, for example, you wanted the release specific documentation for Communications Suite 6 Update 2, you now understand that you would use the following URL: Simple, eh?

      On the other hand, when dealing with say, administration information, we made the decision to not publish a release-specific Administration Guide for each new Communications Suite version. This is different from other typical publishing environments, where you would expect a new Administration Guide to be published for each new release, even if little to nothing changed. Instead, in the Communications Suite world, you always go to the same guide (you don't have to look around for version x update y of the guide), whose URL remains the same. For example, the Calendar Server Administration Guide is located at

      So, how do you know if a change was made to a product feature and in what release, you ask? We use a versioning panel to indicate the introduction of a new feature, or a change to an existing feature. Here is an example from the Calendar Server Administration Guide:

      So, to summarize:

      • If you want release notes, and installation and upgrade information, go to the release-specific wiki for the release that you need.
      • For all other content, including administration, customization, developer, and tuning information, go to the "home" (non-release specific) wiki.
      One more note: The home Comms wiki space always has links to the current release specific documentation in the right-hand "Guides" panel. So that's another place to start looking for release notes, installation, and upgrade information.

      Reporting about Unified Communications Suite Documentation, including news, Comms 101, documentation updates, and tips and tricks.


      « January 2013 »