OpenSolaris.org Content: A Writer's Weblog

At the FOSDEM conference in Brussls, Belgium yesterday, we distributed 300 OpenSolaris Starter Kits to the many students here. It was a very exciting day with Simon's Keynote getting good reception and a lot of interest at our booth all day long. So many of the attendees have not used Solaris at all and many still do not know it works well on x86 hardware. As compared to LinuxWorld and SIGCSE conferences, this audience is far younger with most visitors in early twenties and many more having at least heard of OpenSolairs before. We have OpenSolaris running on Mac mini and Solaris Express CE and Belenix on x86 laptops for demonstration. The Mac mini brings most scratching heads and begins the conversations quite well.

The discussion typically then turns to the previous experience with Solaris each attendee might have, their willingness to try it out and, in many cases, difficulty with an installation attempt. We did also have a couple of interesting questions that could imply some documentation needs, as follows:

scenario: User just bought, installed, and configured T2000 Niagara box, wondered how to automate the updates through updatemanager, using command line.

scenario: User has a need to change the hostname for a particular machine on their network, but cannot figure out the way. Answer was to change /etc/nodename. One might think /etc/hostname, but answer is nodename, so maybe this difference could be made more explicit in the information?

In general, there has been an incredible amount of excitement about the Starter Kits, the LiveCDs continue to be a real hit and always people are impressed to see that they exist and can be had for free. In addition, at least 10% of the interested attendees yesterday said that they had already ordered a Starter Kit from the internet about a month ago when they saw the information on slashdot. Unfortunately, no one has actually received the kit they ordered yet, so they are happy to get a copy.

I've met many other contacts this week and had many discussions of curriculum, folks in Holland interested in full-blown four-year University curriculum for OpenSolaris, based on the interest and excitement around the Introduction to Operating Systems: A Hands-On Approach Using the OpenSolaris Project document we developed for the Academic and Research community. I will detail the conversation in another blog, because it is worth more time to relay all of the thoughts on the subject of courseware. We also share our booth with the OpenJDK group, so I've had many conversations about development of a Starter Kit for that project, the time to develop it and the appropriate contacts for getting a OpenJDK kit underway. More to come on that and what types of information it might provide.

I arrived in Berlin, Germany several hours ago. I will participate in the OpenSolaris Developer's conference here next weekend. Jet was not too full, so I had two seats to myself and it made all the difference. I slept off the jetlag enough to get online and remember my blog login, which is more than I'd expected. Tomorrow I'll join in the FOSDEM fun in Brussels to work the booth, distribute Starter Kits, and report here on new conversations about documentation.

Howe Sound kayaking to Hermit Island
Bald Eagle fishing tiny school below
Our floating human-powered vessels
Bobbing seal heads in swimming warm waters beside my paddle
Mussels waiting for high tides to hide too fragile for feet
Where toes and ankles meet spiders and snakes
feathers and shells that crumble into white salty crackers

I photographed them but couldn't catch the big enough small
The feeling of it all rocking and eroding on the wave's rhythm
Washing ashore then pulling us back
Testing the strength of my arms my head to the muscles that will last

We saw no boats or cars or people
Only the occaisional by-plane puttered above well past noon
In as many days as hours we'd spent out in the ocean
We were back in our city by the bay
A part of traffic by car travelling to get somewhere
Rather than go around somewhere

I smile at a child and his greyhound wearing a designer doggie coat
As we pass a homeless man with rags for clothes
I trace my water source and power lines
Figure out the train, the bus ride
Needing some direct action to compliment meager activism

Pay attention to the variety and types of birds and grasses.
Not handsets and sun glasses.
Not poor drinking water and spraying for virus.
Write some of your thoughts down and read them out loud with high energy like honking at cars or cheering the TV.
Tell somebody.

It is late in the day on Oct. 6th 2005, I'm two hours into a new position as a lead writer for the Documentation Community for OpenSolaris, I join the World Wide OpenSolaris User Group conference call. On any other project, it takes weeks or months to have a live communication with, say, the Ambassador for open source, champion-level contributors, kernel engineers, marketing representatives, and new community members. Not OpenSolaris, I meet them all on my first night on the job, on the 9pm WWOSUG conference call.

This work has truly been a thrill-ride ever since, it breaks down all the traditional mechanisms for communication and opens up totally new avenues for technical communication and education.

Brand Z (branded zones) was the topic of the December Silicon Valley OpenSolaris User Group meeting. But, the star had to be the food, I enjoyed tamales, curry chicken with rice, spiral ham, and a lavish assortment of cookies. Luckily, I avoided sleepy-food-coma and learned a lot about branded zones. Brand Z enables you to develop and deploy Linux apps in a Solaris zone. So, you can use all the Linux dev tools you need to develop and then debug with Solaris goodies like DTrace. The best of both worlds, to be sure.

We've published an HTML tarball of the Device Drivers Tutorial on the Doc Downloads page of the OS.o documentation community portal. We felt this doc might be useful in conjunction with the SolarisUniversity Challenge. This was a joint effort between the OpenSolaris doc community leaders and sponsors, so we hope to assist folks who are new to writing device drivers and give an idea of how one might document, test, and debug.

In response to community request, a tarball of the ZFS Adminitration Guide HTML is now available from the OpenSolaris documentation community. TGIF & RTFM!

Hi,

The final Sun N1 System Manager v1.2 Docs are now available!! Its been a blinding, whirring, blenderish 2.5 months since our debut of the v.1.1 documentation. I'm a person who likes completion much more than planning, the end game, more than the QA. So, today is another milestone in the walls of membrane a technical writer conceives of and nurtures to enable the passing through of information from the nucleus to the rest of an organ and back again.

To join in the mytochondria subscribe to the docs-discuss alias at opensolaris-DOT-org by sending email to docs-discuss-subscribe-AT-opensolaris.org. Or watch it here.

My first time at the Silicon Valley OpenSolaris User Group meeting in October was a very exciting and warm welcome to the OS project for me. I'm thankful to have met two community members who are passionate about documentation in all of its forms. It is wonderful, as a technical writer for a large engineering company, to find folks who want to talk about, ponder, discuss, complain, applaud, and just generally get interested in the publications that we produce. And we did, until nearly midnight, on the steps of the Santa Clara auditorium.

Now that I've ramped up on the OpenSolaris project, we're starting to make real progress on some of the topics that I discussed with our community on those auditorium steps. We've updated the Documentation Community web site with the following high-priority items:

• New front page content that is more approachable.
  
• New Big Doc List that provides a catalogue of links to all the docs that apply to OpenSolaris.
  
• New Contributor Resources page that provides links to the formal Solaris 10 documentation.
  
• New page for the Glossary
  
• Updated Documentation Roadmap.
  
• New page titling to improve usability.

It has been a big week for getting face-to-face. I've been reading posts and updates on benr's site for at least a year or maybe two by now. And this week I had my first real conversation with Ben on the docs-discuss alias. This is big for me because I want to know the members of the OpenSolaris documentation community, and to have Ben in the mix is awesome. He knows how to build a site that caters to UNIX sysadmins. In response to Ben's post, I've started working on a draft of style guidelines in earnest. That was yesterday.

Wednesday, I had lunch with a fellow techwriter who works on Sun Studio. Serendipity, because Bonnie sent a message about OpenSolaris keeping current with the Sun Studio compiler version used by commercial Solaris just this morning. After talking with Kami in Sun Studio pubs, I feel I have a better sense of the compiler audience and their particular doc needs and trends. Kami, I await your first blog entry and look forward to our next luncheon!

Tuesday, I had my first full dental crown installed. This was a horrible thing to have happen when I needed my brain so badly this week. It resulted in a lot of headaches, but is getting better each day that my jaw adjusts. blech.

Monday morning I met Jim and Derek in person for the first time. These guys are really cool and they gave me an unusual amount of their time considering I just dropped by their offices unannounced. They are interested in editorial and docs and that makes my writer-heart sing.

Then, an hour later, in the cafeteria, I spottted Johnathan getting his lunch. Shizam, he really eats off of a tray like the rest of us! I just walked by staring at him with a big dumb grin, wishing I had a secret bloggers handshake or something. Like, hey, you're my boss's boss's boss's boss's boss and here we are picking up ketchup packets at the condiment stand like compadres! I shoulda known this week would be grand...

I've been awarded a great new position as a tech writer for Open Solaris. I will replace Ginnie Wray as community leader and sponsor for Open Solaris Documentation. Ginnie has left a great popcorn trail of her efforts and plans for which I am grateful. I will work with Sue on the project and I couldn't be more excited.

My first goal is to encourage other professional writers in IPG to write here. And to contact those writers who are already blogging and seek them out for more new conversations. At present, I can count on two hands the blogging writers, and I aim to need my toes by the time my transfer is complete. I will update the trunk with links each week so you can meet new blogging writers too.

So, what have I been up to in my first two weeks working 1/2 time on Open Solaris? Mostly research and reading and diving in and trying not to drown.

I've been reading the discussion threads because there is wisdom in what the community already has to say about what should be done to open Solaris documentation. Much can also be learned from researching mature open documentation templates and portals and collaborative efforts.

Soon to follow the participation windup and research summaries will be planning of the effort. You'll find out that I don't like to plan for too long, because software rarely goes according to plan. Why waste time trying to nail down plans? The important thing is to *draft a plan* and then adjust it early and often. Iterate, deliver, communicate, iterate, deliver, communicate.

By Nov 1st, I will officially be a leader on the OpenSolaris site and will be fully able to contribute to the portal pages. Until then, I will log my experiences, progress, and status here.

The information product team that is responsible for technical documentation and training spent three days last week hearing from N1 stakeholders. It was a unique opportunity to gather and discuss the information that supports the N1 product line.

We listened to stakeholder feedback during the first day, heard from the N1 CTO on the second day and did brainstorming activities in teams. And on the third day I rested

There was wrap-up in Broomfield, the site of the offsite. I missed this part in favor of a previously planned kayaking trip to Del Norte county, CA. I highly recommend such an outing after a long week of concalls and 'theory work' to come up with new ways to teach users about Sun products in the systems management space. Big trees provided awesome shelter from hard rains on our tent and fireside serenity made way for stargazing and planet watching.

During the summit we discussed new ways to participate in the community around us. We talked through the coming year and the complexities of creating a model for learning and teaching the community to use N1 products to build out data centers.

We found that, in addition to technical information about supported configurations and functionality, the biggest improvement to our content would be real-world data and examples for use in the field. The challenge is to provide information that describes high-scale monitoring, provisioning, and maintenance an order-of-magnitude greater than the industry has seen before. No pressure. This is only priority 1.

While that is cooking, I will begin to add new types of content that fill in other holes in the N1 documentation picture by using my weblog. These pieces will be in support of system administrators using the Sun N1 System Manager. They will attempt to provide a newly paved two-way street to formal tech doc authors (me) and new users of N1SM 1.1 (maybe you?). Community building. This is the most fun.

Now that Sun N1 System Manager 1.1 is generally available, we are holding an information summit with stakeholders to assess, adjust, and plan for the future.

It is an exciting time for me. The research cycle has begun afresh, the bugs are starting to trickle in, and I'm on deadline because new sweet boxes are on the way.

The information summit will allow us to listen and learn from internal customers who interface with external customers in the field. We will discuss the information story for N1 going forward with the thought leaders in data center network systems software development.

I develop online technical documentation using the following tools:

• Solbook - a custom version of DocBook with many restrictions
  
• Arbortext Epic editor - an SGML editor with customizations for Sun
  

Using these tools, I can publish information in the following formats.

• PDF
  
• HTML
  
• JavaHelp
  
• roff
  

I love using Epic and the Solbook DTD to create technical documentation because it allows me to focus completely on the technical content, structure, and flow. I can leave the formatting to the tools.