From dmr to DITA (DocBook, too)

I was sorry to hear of the passing of Unix and C language pioneer Dennis Ritchie. I only met him a couple of times, but found him to be gracious and humble, despite being one of the smartest people I’ve ever met. It was, however, heartening to see the outpouring of stories and to see him widely recognized for his status as a founding father of modern computing.

The obituaries rightfully acknowledge his foundational work with the C language and Unix, which is his primary legacy. However, he also had a strong influence on computer documentation. He and Ken Thompson originated the Manual Page (aka Man Page) and documented the commands, system calls, and APIs for Unix using that format.

Continue reading

Posted in Commentary | Tagged , , , , | Comments Off

Ada Lovelace Day

In honor of Ada Lovelace Day (findingada.com), I’d like to honor a woman who is completely unknown in the publishing and software worlds that I normally inhabit.

When I knew her, in the late 1970′s, Rosemary Killam was a professor of music theory at North Texas State University (now the University of North Texas). She gave me a part-time job writing computer programs for computer-aided instruction in music theory.

However, much more than giving me a job, Rosemary helped/cajoled/browbeat me into more of my professional “firsts” than anyone else I ever worked with. She was the first person to hire me as a programmer, helped me write my first conference paper, commissioned my first real (as opposed to student) computer program, and guided me through my first grant application.

She was also the first feminist I had the opportunity to interact with in any significant way. When she passed away in 2007, we had been out of touch for at least 10 years, so I googled her name and found articles, letters, and on-line discussions centering around feminism and the music world, including a fascinating article titled: Cognitive Dissonance: Should Twentieth-century Women Composers be Grouped with Foucault’s Mad Criminals? that attempted to explain why four recent (at the time) books on twentieth-century music nearly totally ignored women composers, despite all four of these (male) authors having been strongly supportive of women composers in other contexts.

I also found a series of on-line conversations that highlighted her ability to have serious, strongly-opionated, and at times combative discussions with people she disagreed with, and yet still maintain civility and respect for her correspondents.

So, why is a music theorist who specialized in feminist issues someone to honor on Ada Lovelace Day?

  • She was an early advocate for using technology in music pedagogy. My work with her was to write programs for computer-aided instruction in ear training. She wanted to do whatever she could to help students improve their skills, and she saw that computer-aided instruction could be a big help in that area.
  • She taught me that writing was important regardless of your discipline, and encouraged me to write papers and document my work.
  • She had high standards and would not accept mediocre work. Anytime I think about cutting corners or taking a short-cut, I remember her standards and usually (I wish I could say always:-) take the extra effort to do the right thing.
  • She was fearless. I never saw her back down from anyone or be intimidated by anything. But, she would also engage with anyone on any topic in a constructive way, without anger; she reserved her anger for shoddy work.
  • More than anyone I have worked with before or since, she was interested in and supportive of the students she taught and the people she worked with.

We don’t always take the time to honor our mentors and thank them for the impact they have had on our lives, and truthfully, I didn’t realize the impact that Rosemary had on my career until years later, and I never had the opportunity to thank her. So I’m glad Ada Lovelace Day gives me a belated opportunity today. Thanks, Rosemary.

Posted in Commentary | Tagged , | Comments Off

The Wiki Dilemma

There was a new review by Tony Chung of Alan Porter’s WIKI: Grow Your Own for Fun and Profit at TechWhirl this week.

The review got me thinking about the use of wikis, and more generally, about why wikis are not used as much as they might be.

Continue reading

Posted in Commentary | Tagged , , | 1 Comment

IEEE Customization

A while back (2007, to be exact), I wrote a DocBook XSL stylesheet customization (fo for pdf) that converts a DocBook article into the format specified by the IEEE for their conferences. I’ve revived the customization, and am posting it here as a gzipped tar file.
Continue reading

Posted in DocBook | Comments Off

Monden-san

From 1986 until 1989, I worked in Tokyo, Japan, at an AT&T subsidiary called Unix Pacific. Our official charter was to license AT&T’s Unix operating system in Japan and Asia. To do that, we needed a version of Unix that would work with Asian languages; thus, our second charter was to work with Bell Laboratories to create international versions of Unix.

Our development manager was Jiro Monden, or Monden-san, as we all called him (I never heard anyone call him anything else, I’m not even sure his wife called him Jiro). Monden-san managed a team of five or so developers. His team was responsible for supporting EUC (Extended Unix Codesets; see EUC on Wikipedia for more than you really need to know about EUC). The main historical importance of EUC is that it is the grandparent of the UTF-8 coding scheme for Unicode.

My responsibility was at first somewhat vague; I was brought over because I was familiar with the latest version of Unix, having been part of the development team. Beyond that, my job was to support the development team in any way I could. After bouncing around on various projects, I ended up on a project where I was the manager of five engineers who came to our Tokyo office from Beijing to work on a joint project with our team.

At the time, my sole managerial experience was supervising a few part-time student employees in a computer center. So, I needed an example and a mentor, though at the time I wasn’t aware that I did (youth and hubris, I guess). Our managing director provided one example, but for direct management of engineers, I started watching Monden-san.

Unlike nearly any manager I’ve seen before or since, he kept a perfect balance of strength (he could dress down a miscreant with the best of them), flexibility, common sense, and humor. His team delivered on time and with quality. They met their commitments and had fun working; in fact, the morale there was as good as in any group I’ve worked with. He was nearly always smiling, and so was everyone in his group, even when they were under the gun with a tight schedule.

He taught me the importance of keeping your eye on your objective. It is very easy to get tied up in the details and lose sight of where you’re going. He was able to adjust schedules, re-assign resources, and juggle priorities to help his team reach their objectives. He could keep a firm eye on the objective, and a flexible hand on the means; not easy and not common.

Monden-san never said a word about it to me, but he was an equal-opportunity manager in a country that, at least at that time, had very clearly defined roles for men and women, as well as racial minorities (Koreans in particular). Monden-san paid no attention to that, and hired people based on their engineering ability, not their gender or national origin. We had as diverse a group of engineers as you could have in Japan.

Monden-san passed away this week after a long illness. I will remember him as a mentor whose example set me on my path as a manager. But, I will also remember a man with an unforgettable smile, who knew how to enjoy life.

At a Japanese funeral, you frequently see a picture of the deceased; usually a very solemn, formal photograph. At Monden-san’s service, the picture shows him smiling, of course.

Monden-san

Posted in Commentary | Tagged , , , | 1 Comment

Social Media is not an option

If you think you can ignore social media, if you think it is an option you can take or leave, think again. Sooner or later it will find you.

This week, the Society for Technical Communication (STC) proved this in a painfully public way. For those who haven’t followed the story, check out Sarah O’Keefe’s excellent blog post, and if you want more, search for #stcorg on twitter.

The short story is that the folks who are responsible for a website rework made a boo-boo; they left a beta/alpha staging site open to the public, and when the public (or two members thereof) tried it out, the website owners made another boo-boo by blaming a delay on those folks.

There are all sorts of comments that could be made about this, and if you check out the #stcorg stream on twitter, you’ll find a lot of them. I’ll resist the urge to pile on so I can make a simple point:

Social Media is no longer an “option,” it is a requirement.

Social media is like mass media for the rest of us. If the major news networks claim that a political candidate was a draft dodger or isn’t a citizen, that politician must respond to remain credible. If you or your organization screws up, or is perceived to have screwed up, and it gets out on social media, you must respond to remain credible. Even if the response is just, “gee, I screwed up, I’m sorry,” it’s better than silence.

I’m not sure you need to go all out with a “social media blitz,” or spend hours participating on every social media platform, but you need to listen, and you need to have people who are able to respond quickly when things happen. This means people who have both the authority to speak for your organization and the ability to speak intelligently.

Posted in Commentary | Tagged , , | Comments Off

The Official Indie Book Reviewer List

Reviews are critical to the success of your book, but it is difficult for niche publishers to get a review from the “mainstream media.” The major newspapers and magazines are overrun with books to review, and they are unlikely to see, let alone review, a book from a publisher they’ve never hear of.

Fortunately, there are now hundreds (if not thousands) of bloggers who review books. Now the challenge is finding a reviewer who reaches the audience you’re trying to reach, reviews books like yours, is credible, and has a large readership. Sorting all that out can be a real pain, but I ran across a new e-Book, The Official Indie Book Reviewer List, by Christy Pinheiro-Silva, that may help you out.
Continue reading

Posted in Book Review | Tagged , | 1 Comment

It’s not the tool, it’s the writer

Every musician has heard the old saw, “it’s not the instrument, it’s the musician.” If you give Pat Metheny your beat-up Strat copy and a practice amp, he’ll still sound like Pat Metheny.

The same thing holds true in technical communication. We obsess over whether we should use FrameMaker, ArborText, InDesign, Word, etc., or we can’t decide between DocBook and DITA. The truth is that a good writer can work with any of these tools and create good content, and a bad writer can work with any of them and create crap.

But, there’s a subtler point here. If you take the time you would have spent looking for the perfect tool, and instead dig deeper into your current tool, you’ll be ahead in the long run. It’s better to become an expert using a B- tool, than to be a dilettante using an A- tool.

Corollary: there is no such thing as an A+ tool. Yes, some tools are game changers, but they are few and far between. And, in the words of Eliot Kimber, “All Tools Suck.” Even the game changers suck, the only question is where they suck and how you can work around their problems.

Posted in Commentary | Tagged | 3 Comments

Does a manager need to be an SOB to survive?

In a recent article on BNET, The Real Reason for Bad Bosses, Jeffrey Pfeffer highlights a common, but little noted, paradox. To be a good manager, you need to be positive, supportive, and warm, but to be perceived as strong, competent, and intelligent, you need to be critical and even nasty.

The Two-Faced Manager

While there is a lot of truth to Pfeffer’s argument, he misses an important point. There is no law that says you have to be one or the other. There are two audiences at play – your team and the management team, including your peers and higher level managers – and you are the interface between them. You can and should present a different face to each audience.

When it comes to surviving in the corporate world, being two-faced is not only okay, it is absolutely necessary. You need to be the most supportive, collaborative manager possible in interactions with your subordinates, and you need to be as strong as possible (without being overbearing) in interactions with your peers and higher level managers. Not only does this improve your image (and promotability) with the management team, it also helps to ensure that your team gets its fair share of the goodies.

Strong Does Not Mean Nasty

The other common mis-perception (which Pfeffer clearly does not share) is that you need to be visibly “tough” or even nasty to be strong. While this kind of behavior may make you look strong in the short run (and even longer in a dysfunctional organization), it is ultimately a sign of weakness, not strength, and will eventually be seen as such.

This does not mean that you can’t be firm with your team, and critical when called for, and it doesn’t mean you need to turn into an SOB when you interact with managers. And, it especially doesn’t mean that you need to lie to either audience. Instead, you need to understand that there are two audiences, with different needs and expectations. To be a good manager for your team, your organization, and your career, you need to give each audience what it expects and needs.

Posted in Commentary | Tagged | 3 Comments

What STC can learn about certification from the FAA

There has been a recent flare-up of discussion about certification for technical communicators and the forthcoming certification program from the Society for Technical Communication (STC).

Over the course of 100+ messages (I stopped counting at 100:-), the discussion has ranged from serious (does certification help or hurt job seekers) to off-the-wall (is the STC an evil organization bent on world (or at least tech comm world) domination).

However, to me, two critical questions have gotten short shrift: what can any certification program reliably say about the competence of an individual in a particular role, and how can participating in a certification program improve an individual’s skills as a technical communicator?

In short, can certification perform a useful function for both participants and hiring managers? I think it can, and I would suggest that STC look towards the FAA pilot certification program for insight into both the strengths and limitations of certification.

Continue reading

Posted in Commentary | Tagged , , | 9 Comments