HeraTech

June 30, 2010

Professional Organizations and Value

Filed under: Uncategorized — heratech @ 10:14 pm
Tags: ,

Belt tightening I had a bit of a revelation last week. On my way home from Scrum Club last Thursday my brain was a whirl with thoughts, making connections between the speaker’s presentation and not only my work life, but my personal life as well.

And then I got to thinking about the pros and cons of the different professional organizations whose local meetings I attend.

The first organization charges $215 a year for membership dues, $20-30 for monthly meetings (which pays for dinner), frequently schedules meeting topics that have absolutely no relevance to my career or interests, and when I do attend the meetings my impression of the members is that they’re old, out of touch with recent trends, not particularly technical, and even worse, completely uninterested or unwilling to learn or change.

The second organization has no membership fees of any sort, doesn’t charge for meetings and even provides free pizza, recruits excellent speakers sometimes with national reputations, and the membership generally impresses me as intelligent, professional, and technical.

Which professional organization would you rather belong to?

Yeah, me too.

So despite the fact that I wrote a post last year about how I was sticking with the Society for Technical Communications, I don’t see myself renewing my membership next year. I’ve been trying to be more active in the STC, posting to my mailing lists and attending local chapter meetings. I still hate leaving an organization when it’s in trouble, but I stuck with them this year, despite the fact that my dues went up by over $100 and I still lost benefits under the new a la carte pricing system. My STC dues have more than doubled in the past five years. Between the bad economy and their huge price increase, is it any wonder that the STC has had a major drop off in membership this year?

Over the past couple of months, as underemployment has pinched my budget, ROI has become more and more important to me. But the good news is, there are plenty of free resources out there, if you’re willing to look for them.

I’ll miss the STC Lone Writer’s Mailing list. But I’ll still have the TECHWR-L mailing list and HATT Yahoo group and various blog feeds to keep my G-mail inbox supplied with professional development reading material.

MadCap Software has been offering a series of free webinars. Some of the webinars are specifically for MadCap products, but many of them are tool neutral. I recognize the names of the majority of the presenters, which means they’re either industry experts or active on one of my various mailing lists. So far the couple of webinars that I’ve attended have been worth my time to attend. And you can’t beat the price.

The STC charges $79 for webinars. I haven’t signed up for one yet because I’ve attended more than one poor workshop or webinar where I wished I’d spent the money on a good book instead of the event. So far the STC’s track record for events hasn’t done anything to convince me to part with the money for a webinar.

But I think that even more than the money, I’m worried that the STC is out of touch and that the membership is graying. I’m often one of the youngest people in the room at our local chapter meetings. The Boston chapter is supposed to be the second largest chapter in the country (Silicon Valley is number one, natch), but despite the fact that Boston is a college town and has several local universities with TW programs, we don’t seem to be attracting members in their 20s and 30s.

And the fact that national actually put out a request for someone to write an RSS tutorial rather frightens me. I’ll admit that I was rather late to join the RSS party, but I somehow managed to set up three RSS feeds on two different readers without anyone providing me with a tutorial. It’s not that hard people!

So for the foreseeable future, I think I’ll be focusing my professional development and networking efforts on the local organizations that are providing free events in the Boston area:

Nashua Scrum Club

Agile Bazaar

Agile Boston

January 11, 2010

Agile Tenet #9 – Attention to Excellence

Filed under: Uncategorized — heratech @ 8:54 am
Tags: , , ,

Area nine. Ninth in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.

*****

Continuous attention to technical excellence and good design enhances agility.

I met Abby Fichtner at the Nashua Scrum Club. Her card included the address of her blog, the Hacker Chick, and since like the elephant’s child I have an insatiable curiosity, when I got home I surfed on over to check out what she writes about. She’s got some great posts over there. I particularly like this one about Craftsmanship where she states that one of the most important lessons of Agile is “the only way to go fast is to go well.”

“How many times have you been significantly slowed down by bad code? Martin asks and we can be sure all programmer hands went up. “Then why did you write it?” he asks. There is laughter because of the truth in his question. We have all been slowed by bad code and yet, we continue to allow bad code to be written on our projects. And why? Because we didn’t have time to write it well?”

“We must not write bad code. Period. This is a fundamental issue of professional behavior.”
– Bob Martin

As I’ve been learning about Agile, there seems to be quite a bit of emphasis on not just delivering software, but delivering better software. When we started our move to Agile at my company, there was a lot of emphasis on testing, with added unit tests, test harnesses, test plans, etc. I’m not sure if we meet all the requirements for test driven development, but we’re probably pretty close. Which means that our next release is going to be of significantly higher quality than our last one. This is good news for our customers, and will hopefully translate into better word of mouth and better sales. I appreciate that the Agile emphasis on speed does not mean that we’re producing sloppy work, but also focusing on quality product.

Abby’s post on Craftsmanship led me to this one where she writes:

“And I just keep thinking back to Clean Code’s preface: if we’re to call ourselves professionals, we have a responsibility to act as such. And maybe that means we really do need a 5th element for our Agile Manifesto: We value Craftsmanship over Crap.

So, how do you adopt this tenet to Agile technical writing? As Agile TWs we need to figure out how to not only write faster, but how to write better. And I’ve been lucky enough to have been exposed to automated tools that can help you be a better writer.

At a previous job we were implementing a pilot program with acrolix acrocheck (which seems to have been replaced by acrolinx IQ) a style and grammar tool that was designed to reduce translation costs. The tool had a number of different features: it checked spelling and grammar, checked a variety of common style rules (as defined in the more popular style guides), and could be programmed to check for in-house terminology and style. You could also use it with Microsoft Word, Adobe FrameMaker, and RoboHelp. Part of our pilot program was figuring which rules we wanted to keep and which we were going to disable. For example, our product had a Users application, so we had to decide if we were going to keep the rule “don’t use the word user in your documentation.”

I’d always thought I was a pretty good writer, but the first time I ran the tool against one of my projects, I was absolutely horrified by how many errors were flagged in my document. It’s a good thing that my attitude towards editing is that is necessary for improvement, or I’d probably have been curled up under my desk. My three most common errors were sentence length, future tense, and passive voice, but there were plenty of other problems. Most of them easily fixed.

I used acrocheck for at least three months as part of our pilot. And one of the things that I noticed was that it was starting to improve my writing, in much the same way that using spell check consistently finally teaches my fingers the correct spellings of words that I initially misspell. I was starting to catch myself using passive voice during my writing process, before I ran the tool against my draft. I also started noticing when my sentences were creeping towards run-on (although, as you may have noticed, it’s still a problem I struggle with!).

The acrolix product is enterprise level, and priced accordingly. Not something that I’m likely to be able to access in my new role as Lone Writer. But if you’re a FrameMaker user, I’ll point you towards the download for SDL Author Assist a FREE grammar and style checking tool. I’ve played with it, and it is worth the upgrade if you’re not yet on FrameMaker 9.

If we’re going to call ourselves professionals, we have a responsibility to act as such. We value craftsmanship over crap.

I love this. This resonates so profoundly with me. This just may be my new motto.

*****

Here is another post on the fifth element for the Agile Manifesto – Craftsmanship over Execution. Read through the comments, they’re great.

December 7, 2009

Why I am Renewing my STC Membership

Filed under: Uncategorized — heratech @ 8:25 am
Tags:

Society for Technical Communication logo When I sit down to pay bills tonight I will be renewing my membership to the Society for Technical Communication (STC). There were major changes in the dues structure this year, including a change to a la carte benefits that resulted in a rather hefty price increase. It’s been a couple of years since I worked for an employer that picked up my STC dues, but even though I’m currently underemployed, I’m still renewing my membership. Here are my reasons why.

Job Bank
When you’re looking for work you need to remember that the candidate screening process is a two-way street. Companies are weeding out candidates that are a poor fit for the job, and likewise, you should be weeding out companies that are a poor fit for you.

If a company lists an opening on the STC job board, I can be pretty sure that they already know that a TW is not an administrative assistant. I won’t have to spend my interview explaining what a technical writer can do for them. Instead I can focus on what *I* can do for their company. I’ve had bad jobs and bad bosses before, and have reached the point in my life where no amount of money makes up for a job that I can’t stand or is so stressful that it affects my health. I’m looking for work that I will enjoy and where I can make a contribution. As Whitney Postus recently posted, “Life is too d*mn short to spend it on things that don’t twirl your beanie.”

Job Definition
The STC has been working with the BLS since 2007 to update its definition of the technical communications profession. “Having the US Bureau of Labor Statistics recognize technical writers as a profession distinct from all other writing professions independently confirms STC’s claim that not all writers can do technical writing,”

This is a huge win for the STC. Previously the US Department of Labor put all writers in the same category. Technical writers were lumped in with playwrights, novelists, journalists, and poets. Yes, some writing skills are universal, but novelists don’t need to know CSS. And Playwrights don’t tend to use writing tools like AuthorIT, Flare, FrameMaker, or RoboHelp. And poets definitely don’t need to know DITA or XML. The list of additional skills that may be required by technical writing is long, and probably fodder for another post.

Salary Survey
When I first made the career change to technical writing, the STC Salary Survey was invaluable. Having salary data broken down by zip code was very helpful, since I live in MA, where the cost of living is higher than in other parts of the country. However the STC has changed how they collect salary data, and the jury is still out on whether or not the new survey is as useful as the old one. If I decide that it isn’t, I may have to resort to using salary.com or glassdoor.com when researching salary data.

Local Chapters / Networking / Workshops
I happen to live in an area that gives me access to two different STC chapters. I am within a half hour of both the Boston Chapter and the New England chapter (which tends to meet in NH), which gives me double the networking and educational opportunities. The local chapters put together workshops that often end up being very timely and helpful. I picked up tips at one workshop that made me look like a hero back at the office the very next week.

Intercom
I really enjoy having articles about technical writing delivered to my door, wrapped up in a shiny pretty package. I like to leave them lying around on my desk at the office, to read on those days when I’ve got writer’s block, but need to do something productive. Yes, I could read it on the Web, but I’m more likely to read it as hardcopy. And it’s hard to leave browser bookmarks lying around so that your coworkers see that you belong to a professional organization.

Special Interest Groups
I’ve been a member of the STC since 2001, and in that time I’ve been a member of a variety of different SIGs: Indexing, Instructional Design, Single Sourcing, Lone Writers. I joined the Lone Writer’s list when I was still a member of a doc group, and they are one of my more educational and entertaining mailing lists. Definitely worth the pittance that is charged for SIG membership. This year I plan to sign up for the following SIGs:
• Consulting and Independent Contracting
• Emerging Technologies
• Lone Writers

The STC Needs Support in Times of Crisis
I’ve seen moments of crisis like this in my hobby organizations, where members want to flee what they see as a sinking ship. But leaving is not the way to change an organization. Unless the change you want to see is that the organization withers and dies. There are many talented people out there agitating for change in the STC. I want to give them time to make their changes so that the organization can continue to attract newer, younger members.

And I need to recognize that I get out of the STC what I put into it. I tend to lurk my SIG mailing lists. I need to start posting more frequently, to give back to the SIG communities. I’ve also started attending my local chapter meetings again. I’d love to participate in the competitions, but unfortunately they happen in the fall, when my weekends are completely booked with other activities. But since I cannot participate as a judge, I will start working again towards the goal of entering my work as a participant. Years ago I submitted one of my first projects and received some very useful feedback.

Professional Organization
And I have my own personal reason for continuing my association with the STC. Before I was a technical writer I was a secondary school English teacher. When I started my second year of teaching I was strongly “encouraged” to join the teachers’ union. Joining was technically voluntary, but in reality, it was socially unacceptable to be a non-union member in our district. The only reason I’d avoided the peer pressure during my first year was because everyone knew I was planning a wedding, and union membership dues were expensive.

The word “union” means blue-collar workers to me: seamstresses, hotel chambermaids, electricians, plumbers, etc. When I worked briefly for UPS in college, I was a member of the Teamsters union. While there are white-collar professions, like airline pilots, that have unions, most of the professions that require a college education are represented by a professional organization, not a union. I know it is mostly semantics, but it always irked me that teaching, a career that requires a minimum of a Bachelor’s and usually a Master’s degree, is represented by a labor union and not a professional organization.

So I’m thrilled to finally be working in a career that has a professional organization. And even with the increase, my STC dues are cheaper than the initiation fee that I paid to join either the teachers union or the Teamsters. While I know this may not be an argument that sways anyone else, it has some very powerful symbolism for me and the way I think about my chosen career.

*****

Other folks who have blogged their thoughts on STC membership

Paul Pehrson – The STC Crisis: the Take of a “Young” Writer

David Farbey – Does the STC Deserve to Survive?

Reprint of Monique Semp’s letter on the Lone Writer’s SIG

November 23, 2009

Examining My Writing Process

Filed under: Uncategorized — heratech @ 8:24 am
Tags: , , , , , ,

Last Wednesday’s STC meeting got me thinking about my writing style again.  While I’m always writing, it’s not a linear progression from spec to outline to topics to completed project. 

Until I started working in an Agile environment, my progress on a project went something like this:

  1. Read the design specifications and functional specifications.  Try to get an idea of what features were being built.  If I was very lucky, the specs would include a use case, describing what the customer wanted the software to do.
  2. Count up the number of new applications, tabs, subtabs, actions, dialog boxes, buttons, etc.  This is usually the point when I could start estimating doc effort, as each feature and/or task will usually result in at least one new topic, with a small fudge factor added to cover additional concept or reference topics that might be required.
  3. Generate an outline based off the projected UI features.  Each tab or subtab generally gets a concept topic.  Each action, button, or dialog box usually gets at least one task topic, and sometimes two (as in “creating a widget” and “deleting a widget”).  Estimate the number of concept tasks for toolbars, types of widgets, possible widget statuses, commands, etc.
  4. Start writing procedures.  Open this, select that, enter something, click save.  If I’ve got a well written spec I can often start on a draft before the software is even coded.  Sometimes you can write a complete draft of procedure before the software is even stable.  But it’s more likely that I’ll end up writing a partial procedure with the first several steps of a draft procedure then write myself a note that “Click X and what happens next? Software crashes as of Build# on Date ##/##/##.” 
  5. Next I generally add reference material.  Depending on the software, it might be documenting toolbar buttons, icons, commands, possible statuses, etc.
  6. The last thing that I usually write are the concept topics: overviews of new features, descriptions of new tabs, subtabs, screens, best practices.  It usually takes a while to really “grok” the software and how customers will use it.

When we first made the switch to Agile in January 2009, my manager wanted to manage me like the rest of the development team.  The developers had user stories, I had documentation stories.   The developers generated a list of tasks and then estimated story points for their stories.  I generated a list of tasks and topics and attempted to estimate my doc stories.  The developers kept a burn down chart, and I did the same. 

The only problem was, writing documentation is not like writing code and I don’t have a linear writing process.  I don’t tend to start on a topic, write it, and move on to the next topic.  I tend to work on multiple topics at once, writing as much as I can on one topic before moving on to the next.  Sometimes I’ll have an insight in the car during my commute and will need to capture that before I forget it.  I keep notebooks in my car and in my purse so I can scribble notes to myself. 

My manager expected me to work like a developer.  To pick one task and work on it until it was completed.  But I couldn’t write the doc until there was completed code.  And the first four sprints we didn’t have completed code until the last day or two of the sprint.  So if I can’t write until the last couple of days of the sprint, what am I supposed to do for the first three weeks?  (I spent my time closing doc bugs, many of which had been open since before I was hired.)

I wonder how I’m supposed to adjust my writing process to fit into Agile. I’m a multitasker.  I usually work with multiple files open at once.  My brain tends to makes connections between what I’m doing and something that I will be doing in the future, or something that I wrote in the past.  I’m a list maker.  I’m frequently opening up files and making notes of questions, resources, further research to follow up on later.  Part of this is by necessity.  Writers almost never have the luxury of only working on one project at a time.  Especially lone writers.  Right now I’m writing an Installation Guide, working on fixing doc bugs for the next patch release, writing and estimating doc stories for the past several sprints of development.  And my work is dependent on having functional code.  If I try to work through a procedure and the feature isn’t complete yet, I’ll put the procedure aside and work on something else. 

At Wednesday’s STC meeting the two writers said that they document one sprint behind their Agile development teams.  Both of the writers have been doing Agile for three years.  Before we both got laid off, my manager and I had agreed that this was the approach we were going to try.  Now that I’m only working two days a week, I don’t really have a choice but to write the doc after the developers have finished a sprint.

And yet, at the Nashua Scrum Club meeting on Thursday, someone said that if you’re doing testing or writing documentation a sprint behind development that “You’re not doing Agile.”

So, am I doing Agile documentation?  This is a question that I have yet to answer.

November 22, 2009

November STC Meeting – Documentation in an Agile Environment

Filed under: Uncategorized — heratech @ 3:17 pm
Tags: , ,

Last Wednesday night I attended the monthly Boston STC meeting.  The topic was “Documentation in an Agile Environment.”  The discussion panel consisted of two writers, a doc manager, and a QA tester.  At the beginning of the evening the moderator polled the audience and the vast majority of the audience was not working in an Agile environment. From the questions they were asking, it seemed that many of them were completely new to the concept of Agile programming.

During the question and answer period at the end, one of the older members of the audience asked a question about writing process.  She said, “It seems like you start with the outline.  When do you have time to do the brainstorming?”  That struck me as an odd question.  The way she asked seemed to imply that an outline was NOT where you start.  I got the feeling that she thought the proper process for writing was to brainstorm, then write an outline, then start writing.  It made me think a lot about my own writing process and how it might be vastly different from writers of a previous generation.

I learned the craft of writing at the University of New Hampshire. My four years at Phillips Exeter Academy had given me a solid foundation as a writer, but it was at UNH where I developed an appreciation for the mechanics of writing.  And that was probably due to the influence of Donald Murray on the UNH English department.

My freshman composition class used his Write to Learn as our writing text.  And it was through this book that I was introduced to the idea of the writer’s toolbox.  A writer can have many different tools, some that they use all the time, and some that they may only pull out for particular projects.  There is no One Right Way To Write.  And that’s an important thing to remember.

One of the panelists answered her by saying that when you’re doing Agile writing, you work during the sprint to document the feature, then during the next sprint you work on the next feature. “You write it.  It’s done.  You don’t come back to it.”  Which got me to wondering, when do you have time to write conceptual information?  Almost everywhere I’ve worked, the procedures (“how to”) are adequately documented, but what is lacking is information about “why” you use the feature and the “when” or best practice information.  I’ve spent most of my writing career trying to fill these holes.  And it takes time to be able to determine what needs to be written in the overviews and develop enough customer and product knowledge to be able to write examples and best practices.

Donald Murray also wrote the Craft of Revision which also holds a spot on my bookshelf.  While I don’t write nearly the number of revisions that Murray did (he was almost a compulsive rewriter) I do often return to things that I’ve written, give them a re-read and revise my work.  I don’t often do full fledged revisions, but there are often small improvements that can be made. Especially when there is content that was written under deadline pressure where I didn’t understand a feature well enough to write a solid overview.  Or when I have learned something new about how customers are using our product and can add real-world examples. 

I don’t think I’ll be able to write something and then never come back to it.  Luckily there will be sprints when the developers are working on architecture stories or something else that happens behind the scenes and doesn’t need user documentation, and I’ll be able to go back and tweak my documentation.

One of the things I’ve been struggling with is how my writing style fits into an Agile development process.  I’ll be writing more about that in upcoming posts.

*****

Post Script

In writing this post I learned that Donald Murray had died in 2006.  While I was never his student, I learned a great deal from his books, and read his column in the Boston Globe for many years.  It is because of Donald Murray that I think of writing as a craft, and myself as a craftsman.  I also discovered this wonderful appreciation of Donald Murray.

November 21, 2009

Approaching Agile

Filed under: Uncategorized — heratech @ 8:31 am
Tags: , , , , , , ,
Little girl peeking through fence

Sneaking up on it

I think I was destined to become an Agile technical writer.  In the summer of 2008 I was working for a small software company that produced two different products.  After finishing up a stretch of concentrating on the documentation for product A, I checked in with the product B developers in New Zealand.  I discovered that they’d decided to adopt Agile development without telling me. 

I responded the way I always do when faced with a new idea.  I did some research.

I started out by checked the Techwr-l archives for threads that mentioned Agile.  I’ve been a member of Techwr-l since 2005, and since I use G-mail to manage my list subscriptions, it was fairly easy to find the few discussions of Agile from the past couple of years.  Unfortunately, what little I found didn’t sound too encouraging from a tech writer’s point of view.

I also looked through my collection of back issues of the Intercom, the journal of the Society for Technical Communications.  I found two articles about Agile documentation:

  • Adapting to SCRUM: Challenges and Strategies (July/August 2007)
  • Extreme Documentation (February 2003)

Wikipedia and Google turned up plenty of articles, and also led me to the Agile Manifesto and Scott Ambler’s Web Site.   I had to do quite a bit of reading before I finally realized that when Agile proponents were writing things like “Documentation should be just barely good enough.” and “The benefit of having documentation must be greater than the cost of creating and maintaining it.” They were talking about project documentation (design documents, functional specs, etc), not product documentation like User Guides and Help. And with the exception of the STC articles, none of the resources I was reading were talking about what a technical writer would produce, or how they fit into Agile (other than being part of the Scrum team).

I had just started reading Agile Software Development with Scrum when a friend forwarded a job opening to me.  The job description sounded like a very good fit with my skills and interests.  The company was looking for someone with experience working in an Agile software development environment.

By this point I’d learned enough about Agile to know that the way we were implementing it at my company (developers in two different cities, the tech writer and project manager on a completely different continent) was not going to be conducive to my success as an Agile Technical Writer.   And I was intrigued by Agile. I now knew enough to be able to “talk the talk” during my interviews.  During my interview I quizzed the VP of Engineering.  They were still using the Waterfall Model, but were planning to switch to Agile development at the beginning of 2009.  

I liked the idea of getting in at the beginning and being able to shape the way the technical writer fit into the Agile team.   They made me an offer, I accepted, and I started work there in October 2008.

Fast forward to May 2009 and the end of Sprint 4.  The last day of the sprint our company had a layoff, and I was one of the casualties.  Six weeks later they called me back to work part time (two days a week).  So while I’m still working in an Agile environment, I’m no longer embedded with the team working to document the current sprint.  Hopefully that will change as the economy starts to recover.

Blog at WordPress.com.