The Doc Exchange: alan mcclellan's blog

Picked this up from a Glynn Foster tweet; an interesting article about converting commercial products to free and open software: Making Corporate FOSS Successful.

Excellent perspective and some interesting numbers, too: e.g., 

"Some percent of users will be, just that, users (~90 percent), the other roughly ten precent will participant in your community in some way, maybe by asking or answering a question in your forums. The next one is the one that will blow your mind, of the ten percent of participants, only three percent of those will become contributors that fix bugs or add functionality."

"What that means is for every 1,000 users of your software you'll have three contributors."

Not sure where these numbers came from, but feels about right to me. Gives credence to the urge to promote downloads on the front end of the ecosystem and build broad user base.

Must view youtube here: Ed Zander spends about 1.5 hours in an  unscripted interview with Larry Ellison at the prestigious Churchill Club.

Ed Zander/Larry Ellison @ Churchill Club

Some interesting and informative comments about how Sun assets fit in future for Oracle.

Not that easy on the ears, but this is too good. What a hoot. 

The OpenSolaris Jingle

Windows rules the desktop because of its apps, and I'm often annoyed at the ridiculous pervasiveness of things like MS Office. (They literally teach use of MS Office in my daughter's high school as a computer class. Sigh.) But that's the world we live in. If you are required by convention or office protocol to use MS Office (yes, I know there are open source alternatives) or any other MS app and you want to work in an OpenSolaris environment, looks like that is getting easier to achieve. Check out this nice blog entry about using Bordeaux and Wine to do that.  

I may be a little late to the party on this info, but just listened to a very nice interview with Glynn Foster (OpenSolaris product manager) on (Free Libre Open Source Software) FLOSS Weekly. The hosts are Leo Laport and Jono Bacon, who is the community manager of Ubuntu.  Check out the interview here. It runs about an hour, and it's nice perspective on OpenSolaris from prominent folks in the open source community.

I just joined a very promising organization focused on open source documentation: http://writingopensource.com/. Looking forward to the exchange of ideas with this group and to take a look at their projects.

As you may have seen on docs-discuss, they are following up their conference last month with a BOF session at OSCON. For more details, see: http://en.oreilly.com/oscon2009/public/schedule/detail/10217

Registration is free:
http://en.oreilly.com/oscon2009/public/content/free

Here's interesting speculation about future use of Sun technology and their role in the enterprise:

Forbes article

I was doing my routine update to OpenSolaris 2009.06 from a build from just a couple weeks ago and ended up having all kinds of problems. First and foremost, after the update (I used Update Manager -> Update All), the new boot environment would only boot to the console login. Would not boot to the desktop. A couple of folks suggested maybe a problem / incompatibility between the ViritualBox Guest Additions I was using (they were old) and x11 in the new OpenSolaris. I was lucky enough to get some help from Evan Layton, who saw my boot problem at the CommunityOne Install Lounge. Anyway, here are the steps I ended up following to get my 2009.06 guest OS / BE running.

* Uninstall VirtualBox Guest Additions in original BE: pfexec pkgrm SUNWvboxguest

* Update Mgr -> Update All
* Start new BE - Only boots to console login
   - Log in and remove /etc/X11/xorg.conf
   - pfexec reboot
   - BE now boots to the desktop
   - Install guest additions
   - pfexec reboot
   Boots to desktop with Guest Addition functioning!

I also had come strange screen resolution issues I had to deal with in the VM, but finally got that working correctly, too. 

Am  surprised more people haven't encountered these problems. Not sure what it is about my configuration that led to the problems...maybe the older version of VirtualBox Guest Additions. Anyway, hope this helps others. I'll try to clean this up and post it to the docs wiki site. Wanted to capture the quick-and-dirty version here. 

Am Tweeting at the OpenSolaris HA Cluster Summit that precedes CommunityOne. Some really informative presentations and discussions. I particularlly liked the panel discussion with industry luminaries from Google, Sun, and Aster Data.  Panelists emphasized that the general population is used to high availabilty for all kinds of data and services. They only stop and _think_ about availability when something isn't available. But not many people really understand what it takes to provide that availability. I really appreciated the comments about simplifying the user interface so that a user can digest what is happening and what to do when there is a catastrophic failure, but not overwhelm them with details. In the same vein, need to provide access to the dials and meters under the hood to the technical experts who need to diagnose and correct those catastrophic problems... give them the tools they need to help.  (I'm thinking of the extenstive technical documentation I've seen that is meant to cover those technical details, but is probably not really consulted after major downtime of an HA system. This is really a software rather than a documentation problem.)  I also found it interesting that the panelists thought that most customers don't really understand their own availability requirements.... Rather, they are budget-driven and focused on trying to address some vague problem with a fixed dollar amount.

I'm often asked to explain the difference between the documentation page at the top level of the OpenSolaris.org site (www.opensolaris.org/os/documentation ) and the documentation community pages (www.opensolaris.org/os/community/documentation) I maintain.  

Awhile ago, I exchanged some email with Michelle Olson, who currently maintains the top-level OpenSolaris.org web site, including that documentation page, and compared notes. Here's what we came up with:

• OpenSolaris.org Documentation Page - The purpose is to aggregate various OpenSolaris content across the .org community and the many projects/communities that support it.  The explicit audience is the OpenSolaris community member looking for supporting information on how to learn about and participate in OpenSolaris. 
• OpenSolaris Documentation Community - The purpose is 1) to support community members who want to participate in OpenSolaris documentation or re-use OpenSolaris documentation and 2) to provide specific support on setting up and developing on OpenSolaris. The latter includes things such  as 'beta' drafts of support information for developing on OpenSolaris, which ultimately find there way into the official product documentation that supports a binary release. The explicit user is the OpenSolaris community member who wants to be involved with documentation. The implicit user is the OpenSolaris user who is looking for support on using, setting up, and developing on OpenSolaris.

So, if you've scratched your head wondering about the purpose of these two sites, hopefully this explanation will help a little

I'm glad to see OpenSolaris books finally hitting the bookstores. (See the OpenSolaris Bible.)  I'd like to give a special shout-out to one of the co-authors, Jerry Jelinek. About 12 years ago, I worked directly with Jerry and he was the primary technical consultant on a book I co-authored (Automating Solaris Installations), so I'm glad to see Jerry stepping out front with his technical know-how and co-producing this book. He's a really smart guy and is able to explain things in clear terms, so am sure this book is a winner. (I still need to pick up my copy. :-)

Also, there's some interesting OpenSolaris book activity going on in Asia. Check out Jim Grisanzio's blog for info on these books from Japan and China.

Folks have been passing around this review of OpenSolaris, which is worth the read. It's a pretty fair-minded take on 2008.11. If you go there, take a look at the first "comment--the one titled "I've been using various Linux distributions for over a decade. When OpenSolaris was..." This fellow  makes specific reference to our " incredible centralized documentation."  That's an interesting counter to the comments we occasionally get that folks can't find what they're looking for. The truth is probably somewhere in between, but it's nice that someone took the time to point out that they've had a positive experience wth the docs.

Before January flees us and, in honor of the month of Janus (the Roman god of doors and gates), who had two faces, one to look forward and one to look backward, I thought I should pause a moment to reflect on what we've done and anticipate what we want to do in OpenSolaris docs. 

• Looking backward
  • Published docs in specific support of the 2008.11 release.
    • All documents open sourced
    • New docs - Automated Installer Guide, COMSTAR Administration Guide, Distribution Constructor Guide, Image Packaging System Guide, Media Management System Administration Guide, System Administration Guide, Managing Boot Environment
    • Great public review of GSG and Device Driver doc in blog: See link here
  • Made initial foray into wiki authoring/publishing. Includes working out...
    • Licensing strategy for wiki docs.
    • "Release support" snapshot strategy for wiki docs. (Although we had to jump through hoops to execute snapshot strategy.)
  • Made navigational and organizational changes to docs community web site. Based on user analysis and community input,attempting to focus on community activity first.
  • Supported 2 Student Pack (A.K.A. BTSK or back-to-school kit) releases (one complete, one in progress).
  • Community activity
    • Opened bi-weekly docs integration meeting to community participation. While participation has been modest, intent is to be transparent.
    • Agenda and minutes shared with community.
    • Stellar participation from Rainer Heilke and Mark Brundage to work through the tool chain to create PDF tarball of open sourced docs.
    • Work to refine and re-baseline metrics on community activity.
  • Supported mini-book of Getting Started material -- Assembled content from multiple sources.

• Looking Forward...
  • Grow community population.
  • Grow community contributions.
  • Assess / prototype OpenSolaris xwiki.
  • Better up-front planning for secondary deliveries (e.g, mini book)
  • Continue to drive/evolve Solaris/OpenSolaris information strategy vis-a-vis OpenSolaris marketing strategy.
    
  • Identify tools needs to support more automation.

I'd like to give a big plug to the folks working on the collaborative blog, The Observatory. These guys are doing a great job of digging into the details of squirrelly OpenSolaris setup and configuration and sharing the fruits of their investigations.

I run OpenSolaris in VirtualBox on MacBook, and pouring through the list of info on The Observatory, I keep finding things I need to do to my installation but wasn't sure how: 1) sharing folders between MacOS OpenSolaris/VirtualBox and 2) configuring audio to work in OpenSolaris in VirtualBox, to name a couple.

Anyway, just wanted to say, thanks, guys. Keep up the great work. Looking forward to future entries.

Usually, technical writers only hear comments on their work when there is a problem...an error in a procedure or a lack of clarity or the like.  But lo and behold, here is an independent blog review of OpenSolaris 2008.11 in which the reviewer adds these comments specifically about the documentation:

The desktop includes a shortcut icon called 'Getting Started with OpenSolaris', which links to excellent documentation on installation, post-install configuration, links to the OS blog and forum, guides on installing OS in Virtualbox or Parallels (Mac), and a variety of commercial support options.

There's also a very useful shortcut to the Device Driver Guide, which is worth its weight in gold to anyone new to this operating system. This is how documentation should be done - full marks.

Kudos to the writers on these projects (Barbara and Alta). The review is quite a good read. You can see it in its entirety here:

OpenSolaris 2008.11: Its Time is Coming