Can I be agile as an individual?

I work for a very large company, and we’re in the process of moving our various software development units to what is called agile development. Some units are there already. Others (like ours) are just starting to look into it. I don’t know when we’ll get there. But I recently went through some training and was pretty inspired.

What agile is

Here are the main values of agile development, as set out in the Agile Manifesto:

We are uncovering better ways of developing software by doing it and helping others do it. Through this work we have come to value:

Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan

That is, while there is value in the items on the right, we value the items on the left more.

This means:

  • Simplicity: less planning, more lightweight processes
  • Rapid turnaround
  • Iterative development
  • Constant adjustments
  • More communication
  • More transparency

What agile is not

There are lots of techniques and tools associated with agile: pair programming, stand-up meetings, cross-functional teams, burn-down lists, and so forth. But these are just some ways to work toward the values in the Agile Manifesto — they are not themselves agile. They are neither necessary nor sufficient. In other words, just because I can’t do stand-up meetings or participate in a cross-functional agile team, doesn’t mean that there aren’t things I can do to become more agile-esque and therefore work more effectively.

How can I be agile if my team is not?

As a technical writer, I follow the development environment I work in. We currently work in an old-school “waterfall” environment (first requirements, then planning, then development, then testing, then bug fixing, then beta release, then more bug fixing, then a commercial release) and I absolutely must adhere to that. I have certain things due at the various stages, and I depend on planning documents from other groups. I can’t ignore this structure even if I want to. In other words, for the most part, I must wait for my development unit to become agile before I can truly be so.

However, even though I am beholden to the milestones of the waterfall schedule that rules my project, there are ways that I can be more agile, even as an individual. Many of these are really simple.

The task board

The task board is the single most important information radiator that an agile team has. (Tom Perry)

A public, tangible (non-electronic) task board is a key part of many agile development environments, especially those using scrum as a project management framework. In its simplest form, the board shows task progress. Team members stand around the board every day to move sticky notes and evaluate progress.

Because the board is public and updated daily by those doing the actual work, iraises the project’s transparency and the team’s accountability, and clearly shows when things are behind schedule. It is more likely to be an accurate representation of where things are than is an MS Project file on a project manager’s computer that is updated weekly (or worse). In addition, it’s lightweight: tasks are described by a word or phrase that fits nicely on a tiny sticky note (some say 3-M invented agile): no heavy-duty specifications are needed.

taskboard

We all have to-do lists. Some are in a notebook, others are online. A task board is really nothing more than a public, tangible, up-to-date, to-do list. And it’s clearly something that an individual can easily adopt.

The secret geek has called the task board, “The most productive and least ignorable system I’ve ever used,” preferring it to tasks managed by software: “Placing an anti-procrastination tool on the internet is like hosting an alcoholics anonymous meeting inside a brewery.”

Better communication

I admit that I prefer email to meetings or phone calls. I work on a team that is largely distributed, and I will send an email over picking up the phone 9 times out of 10. But agile emphasizes individuals and interactions; one of its key principles is: “The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.” This lets people work in the same direction and quickly respond to change.

Face-to-face isn’t often possible for me, given the geography, but picking up the phone is something that I can and will do.

“Responding to change over following a plan”

This is my favorite item from the Agile Manifesto. I have spent far too much time planning and replanning my work. And despite all this careful effort, again and again I would find that that my estimates were off, I hadn’t anticipated or mitigated the right risks, and I didn’t always end up in the same place as the software developers (the design had changed since the specs were written!). For this reason, it was good to hear our agile trainer say that perfect long-term planning is impossible in the “cone of uncertainty” we inevitably have at the beginning of any software development project.

This means a few things to me:

  • Plan less (if I can get away with it!), and focus on the short-term
  • Beat myself up less when I “get it wrong”
  • Fail early, communicate, and readjust

Timeboxing

Many agile projects fix deadlines firmly, but allow adjustments to the scope. This focuses everyone on the most important deliverables.

As an individual, I can use timeboxing to limit effort on my own work so that I don’t have things hanging out on my to-do list forever. This will help me overcome three of my big weaknesses: procrastination, perfectionism, and over-committing to things.

Reduce work-in-progress

I’m pretty bad for having a lot of stuff hanging out half-done for a long time. This isn’t ideal because humans (even girl humans) aren’t so good at multi-tasking. It makes it more likely that details will be missed. And only things done by the end of a cycle can be considered “done” — work-in-progress doesn’t help us if we’re not finished when the deadline hits.

Kanban (a form of lean programming related to agile) recommends that the number of “work-in-progress” tasks be limited to two. So if there are already two stickies in the middle column of my task board, and I want to start on another, I have to finish one first. This sounds good to me.

Advertisements

write for translation… even if you’re not going to translate

Why? Because writing for ESL and writing for translation makes for good technical writing, regardless of whether we have ESL readers or expect the documents to be translated. It makes writing more straightforward, consistent, predictable, and succinct.

In particular:

  • Use simple sentence constructions of subject-verb-object.
  • Use the active voice. The passive voice, although appropriate sometimes, can introduce ambiguity.
  • Use pronouns clearly so that the antecedent is clear.
  • Avoid turning verbs into nouns (nominalization).
  • Avoid phrasal and modal verbs. Phrasal verbs have two or more words. Choose a one-word verb that says the same thing. Modal verbs express the mood of the main verb (“should,” “could,” “can,” “would,” “might,” and “may”). Use these when there is no other way to make these subtle distinctions. Certainly avoid using both phrasal and modal verbs together.
  • Avoid noun strings (more than one adjective).
  • Use positive language: avoid negative constructions.
  • Choose one term for a concept and use it consistently.
  • Do not omit articles and prepositions when they help to clarify the meaning.
  • Avoid wordiness: keep sentence length under 20 words.

Examples
Before:
To ensure synchronization (nominalization) between the two (redundant) controller cards is maintained (passive), the operating system occasionally performs an automatic reload of (nominalization) the standby controller card. To facilitate the automatic reload (repetitive, nominalization) of an controller card, the auto-boot? variable must be set (passive) to true. [40 words]

After:
To synchronize the controller cards, the operating system occasionally reloads the standby controller card. To enable this process, set the auto-boot? variable to true. [25 words]

when is an error not an error?

People … feel emotional about the past. Thousands of comments followed the post. At stake here is really the arbitrariness of so many rules of writing. We respect most of them merely for the sake of consistency.

— Russell Smith (The Globe and Mail,19 Jan 2011), regarding a column about style and typography.

Many grammatical and stylistic “rules” have been drilled into us since early school days. However, a good portion of these are not real errors – the best of our writers make them (Shakespeare, Austin, E.B. White, Orwell).

It doesn’t help that popular style books state the “rules” (The Elements of Style; “Politics and the English Language”), while simultaneously breaking them. This fills writers with self-doubt and confusion.

Q: Which of these are errors?

  • Splitting an infinitive.
  • Ending a sentence with a preposition.
  • Beginning a sentence with a conjunction (such as “and” or “but”).
  • Using the passive voice.

A: None of them.

Compare:

  • Donors have pledged $100 million to dramatically increase learning opportunities for undergraduates. (Split infinitive. Are we bothered? No.)
  • Donors have pledged $100 million to increase dramatically learning opportunities for undergraduates.(Better? I think not.)

Should you revise this sentence?

  • Spell check won’t help you when you have the wrong word to start with.  (Are you worried about the preposition at the end of the sentence? Don’t be.)

So, should we enforce these “rules”?

Yes, sometimes. Consistency is important—it makes the voice neutral, especially even when multiple writers are involved in a project. Adhere to your style guide. And remember that readers are armchair editors who have been warned about the very same “errors.” They will judge you, especially if they notice inconsistencies. People really, really, really, really care about matters of style, grammar, spelling, and the like.

There are people who embrace the Oxford comma, and people who don’t, and I’ll just say this, never get between these people when drink has been taken.

— Lynne Truss, Eats, Shoots, and Leaves

So, break the “rules” if it makes sense – but pick your moments.

don’t hide your actions under a bushel

Nominalization is a fantastic word. Like multisyllabic, it perfectly illustrates itself. It means “the noun form of a verb or adjective.” In this case, the verb is nominalize, which means “to make a noun from a verb or adjective.”

But nominalization is not always such a good practice. Nominizations can (not always; see below) weaken your writing by turning powerful energy-filled verbs into nouns, draining away the action from your sentence. Unfortunately, nominalizations are among the scourges of technical writing. I’m not sure why! Fortunately, once you start looking for them, they’re easy to find and (usually) easy to revise away.

In Style: 10 Lessons in Clarity and Grace, Joseph M. Williams (Canadian Edition by Joseph M. Williams and Ira Nadel) gives some helpful examples of how to find and excise nominalizations from your writing. The following examples are inspired by his work.

Nominalized verbs

In general, writing is more clear when the main action is in the form of a concrete verb rather than a noun.

Compare (VERBS are in all-caps; nominalizations in bold):

  • It PERFORMS a reboot of the system
  • It REBOOTS the system
  • We COME to the discovery that…
  • We DISCOVER that…
  • Please DO a review of the data
  • Please REVIEW the data
  • Customers may MAKE an objection if..
  • Customers may OBJECT if…

NOTE that the action and the verb COINCIDE in the more direct examples. Or, if you prefer (and would you really?): It IS notable that there IS a coincidence of action and verb in the more direct examples.

Nominalized adjectives

Likewise, try to use a concrete verb instead of an adjective. Actions hidden in adjectives usually appear after a form of the verb to be.

Compare:

  • The data ARE indicative of the general trend.
  • The data INDICATE the general trend.
  • Our product IS deserving of such an honour because….
  • Our product DESERVES such an honour because…
  • These examples ARE applicable to our situation.
  • These examples APPLY to our situation.

Exceptions

As with so many “rules” of writing, there are exceptions: sometimes a nominalization is better than the alternative. For example:

  • What we have argued previously…
  • These arguments ….
  • The fact that our service team acknowledges every call…
  • Our service team’s acknowledgement of every call…
  • We will respond to what you request.
  • We will respond to your request.

writing release notes (bug descriptions)

Five or so years ago, I wrote these guidelines on how to write release notes for the software developers I work with. I’m happy to say that I still get asked for copies.

Where I work, we generate lists of release notes directly from our bug-tracking software. For each bug that we plan to reveal to the customer, the software developers write draft release notes and draft workarounds right in the bug tracker, and then technical writers (like me) go in and edit their text. Then, right before a software release, we press a button and get our list of issues for the customer.**

The release notes process likely varies a lot from company to company, but I am posting these tips here anyway in the hope they may be useful to someone else. (I couldn’t find much advice online when I first started working on bug descriptions.) I’ve included sample problem descriptions as well as workarounds.

How to describe a software bug

What do customers need to know? Give them just enough information so that they can recognize and respond to an issue. Things to consider:

  • Symptom—How will the customer recognize the issue?
  • Trigger—What customer action or particular configuration or some combination thereof might cause the issue?
  • Operational impact—What is the effect in the customer environment? (I work in the IP routing domain, so some examples here are things like dropped sessions, accounting errors, access problems, upgrade issues, and so forth.) If there is no impact, or if the issue is display-only, say so.

Examples:

How to write a workaround

Things to include:

  • How can the customer avoid the problem?
  • How can the customer recover from the problem if it does occur?

Examples:

Information to exclude

  • Hidden commands (ones the customer will not see)
  • Customer names
  • Real user names
  • Code snippets
  • Feature IDs
  • Code snippets
  • Low-level details, such as the interaction between internal processes

Always describe the bug as if it were open (even after it’s fixed)

Even if you publish lists of fixed issues, as we do, I recommend you do not revise the bug description to put it into the past tense after you fix the bug. It’s too much overhead. We think it’s enough to include the issue in a list called “Resolved Issues.” Also, this approach will allow you to handle a bug that may be open in one software branch and fixed in another—you can get by with a single description that works for both cases.

Also, if your bug-tracking software includes separate fields for the release note text and the workaround text, you can omit the workaround when you generate your list of fixed bugs.

**OK, it’s a bit more complicated than that!

the problem with miscellaneous

In one of my first jobs (early 90s), I worked for a law firm and—along with 15 other recent grads—was responsible for coding documents relevant to the case we were working on.  Essentially, this meant writing a brief summary of each document and entering it into a database. At the same time, I had to assign some categories: date, author, location, recipient. And the hard one: doctype. Some were easy: letter, memo, medical research report, meeting minutes, map, photo. Unfortunately, however, not everything fit nicely into one of these categories. And, in our little home-grown system, the list of doctypes was not expandable. Relatedly, I guess, the system designer had included a category called “miscellaneous.” As you can imagine, this category ended up being quite the hodge-podge and was the largest by far of the categories by the end of our coding efforts. Not massively useful.

I’ve since come across technical manuals with titles like Performing Basic System Tasks or General Configuration. What do you think might be in these documents? There’s no way of knowing just by looking at the title. But we can guess that they probably house the content that the author didn’t know what else to do with…. miscellaneous content. Again, useless. A document like this exists for the author’s convenience, not the reader’s.