I'd Rather Be Writing » proximity

What I Learned About Tech Comm During 2011

Tom Johnson — Wed, 28 Dec 2011 15:31:48 +0000

This past year I learned a few things. As I approach 2012, I’d like to note what 2011 taught me:

Writing documentation in a wiki suits me for the same reasons I enjoy interacting on the web. The web is interactive, alive, dynamic, collaborative, fresh, and unlimited in potential. A wiki, being online, allows me to partake in the same game-like, community-rich environment that I thrive in.
It’s much better to focus on just a few key projects rather than spread myself too thin. I made the mistake of extending my reach into too many projects this year, sometimes taking them upon myself because the applications needed help. As a result, I wasn’t as informed as I usually am about the most important projects, and it showed. Later I pulled back and ignored everything but my two main projects, and I felt much better with this strategy.
I need to set goals to write at work. It’s astonishing how non-writing tasks can eat up the day. Lately I’ve set a goal to write for 4 hours a day at work. I rarely achieve this, though really this goal has caused me to reflect on what writing actually is. If I’m reviewing forum threads to detect issues to write about, or experimenting with a test system to determine steps for documenting a task, isn’t that writing? The typing part comes at the end and is fairly minimal. Regardless, just setting a timer on my iPhone prompts me to dig into the documentation topics and produce something tangible.
Content marketing, played out in the form of corporate blogging, is kind of boring. Corporate blogging isn’t what I thought it would be. Mostly the corporate scenario is stifled by lack of creativity and freedom to explore. You’re expected to toe the line, to avoid controversy, to vet each post through five levels of approval. Comments from readers are usually brief, unenlightening, and often don’t match the topic of the post. I find technical writing more engaging.
A centralized help authoring system is a neat idea, but I hate the lack of control. The idea with a centralized help authoring system is that you install the system on a server with all your styles defined in one central location; an administrator sets up everything to be a push-button publishing solution, and then everyone else just “focuses on content.” However, when you’re used to designing your own help solution, learning to rely on one (often remote) person is discomforting. I like having some control over the design, layout, style, and publication of my help material.
Community collaboration is extremely tough to pull off. I can’t just assign a volunteer writer a topic and let them run with it. I usually have to either gather the information from a subject matter expert or connect the volunteer with a subject matter expert — and then see them through the process with more hand-holding than I want to provide. Still, community volunteers can generate momentum by the sheer number of assignments I have to follow through with. Overall, I have no idea how to engage community volunteers in an effective way, but I think I can eventually figure a strategy out.
Sitting embedded with my project team is more effective than sitting with other technical writers. Sitting with my technical writing team, I end up collaborating a lot on standards, goals, styles, and other issues — which can be useful and important. However, the core substance a technical writer relies on is project-related information. No matter how many IRC meetings, scrums, iteration reviews, and other interactions, nothing replaces the information and rapport you get through proximity to the project team. However, proximity to the project team is just one element. Proximity to end-users is even more important. (See my post on The Proximity Problem for more analysis.)
Just because my job involves sitting at a desk all day with little movement, it doesn’t mean I’m fated to become a couch potato. By counting calories and following a whole-foods, mostly plant/fruit/grain diet, I can actually lose weight while improving my overall health. I’m not becoming a vegan or anything, but I had no idea how poor my eating habits were. The My Fitness Pal iPhone app gave me a wakeup call. The Forks Over Knives documentary on Netflix also made me question the integrity of the traditional food pyramid.
I’m not that interested in fiction. In the fall, I went through a fiction phase that lasted a good three months. During that time, I read and wrote more fiction than I have for the past 10 years. I eventually lost interest and realized I was more attracted to non-fiction for reasons I can’t entirely explain. I like the immersion in ideas (not that fiction is idea-less, but the ideas are shown rather than explained). I enjoy the sense of being “on top of the game” when I’m immersed in non-fiction (such as findability topics) and blogging about these same ideas. It infuses me with a lot of enthusiasm for my job, this blog, and my overall career.
Metadata is the most compelling strategy for findability, but I don’t know how to harness it yet. I experimented with the Semantic Mediawiki extension in a help system, and I liked the ability to tag and query topics in new ways, but I didn’t explore this strategy enough to be successful with it. I feel that I’ve only scratched the surface. There is so much more to discover. David Weinberger’s book Everything Is Miscellaneous, which explores metadata in depth, was the best book I read in 2011.

Based on what I’ve learned, as I go into 2012, I plan to do the following:

Use Mediawiki more.
Set goals to write more at work.
Focus on fewer projects.
Possibly hire an intern to help with the corporate blog.
Leverage community volunteers for non-writing tasks.
Eat smarter.
Read more non-fiction books.
Figure out metadata and findability.

Note: I do change my mind frequently, so no doubt this list will evolve as the months in 2012 pass by.

Blog Sponsors

The Proximity Problem for Technical Writers

Tom Johnson — Fri, 23 Sep 2011 14:33:59 +0000

Last year I wrote a series of posts about moving from the sidelines to center stage. In the series I described how I transitioned from a low-key, hardly-speaking project member to a key player on the project team, someone with a voice that mattered in project decisions. But recently, with some projects, I’ve come full circle, moving back to that initial position of a fly on the wall.

The changes had a lot to do with location. Previously, each technical writer was embedded in a specific group. Most of us were stationed on different floors, in proximity to the developers, interaction designers, quality assurance engineers, and project managers for each project.

This proximity was useful for staying in the loop with project information, but it did nothing for our technical writing team. We used different tools, didn’t follow a common style guide, and came up with our own processes and content models.

Because we wanted to try to build some momentum towards standards, we decided to consolidate our group, sitting together in the same row of cubes. We were no longer embedded within specific project teams, but rather centralized as technical writers in a common location and shared throughout the organization.

In the previous embedded-writer model, I looked longingly towards our once-a-week meeting with technical writers, holding it as the highlight meeting of the week. But now that we were sitting together, it was like a team meeting all day long. Coordination and morale skyrocketed.

As the weeks passed, we started to form some standards. We decided to standardize our toolset, first of all, so that in case one writer won the lottery and left the organization, another writer could seamlessly fill the gap. After weeks of research, and through the luck of another group that already purchased the solution, we adopted and implemented a new help authoring system. We then attacked our style discrepancies, and quickly adopted a 42-page guide of stylistic decisions.

We were gaining momentum fast, and acquired our own servers to run help, injected a documentation template into the project manager process, formulated a content model for help, designated a team member to be the tools administrator, and more. We were flying as a team. We even stopped holding team meetings because anytime we needed to meet, we could just swivel our chairs and raise an issue. Our close proximity led to a brilliant flow of communication.

In the back of my mind, I knew that we had lost some rapport with the project teams that we no longer sat next to. But it didn’t hit me how detached I had become until, about a year later, I attended a two-hour meeting with one of my projects and found that I had nothing to say at all. All the momentum I had previously accrued as a key project voice seemed to slip out from under me.

Proximity and Communication

Sitting silently in the project meeting, not contributing towards interface text, nor quality assurance, nor jumping in on broken functionality, nor even on training strategies, I realized that my sacrifice of proximity with the project team had resulted in my impotence on the project team. I no longer had the same voice, nor was I someone anyone paid attention to. I had become that quiet fly-on-the-wall technical writer, the one whom no one expects anything from except a help file.

I’ve learned that proximity to any team makes an incalculable difference in the role you play with that team. Grouped together with other writers, we actually formed standards for the first time in years. We felt like a team. And separated from project teams, I fell off their radar, and they off mine.

This, then, is what I’m calling The Proximity Problem. The closer you are to a group, the more you interact with that group. But you can’t be everywhere at once, so you have to choose the group that gets priority. Given these dynamics, is it better to be embedded within project teams or within a technical writing team?

Comparing and Contrasting Benefits

Embedded within project teams, I did much more than technical writing. I logged bugs, critiqued designs, guided project managers with feedback from users, and was generally go-to guy for new team members who want to ramp up on the project. I became a subject matter expert on the app itself, which led to my being a key member with a voice at the table.

Embedded within the technical writing team, I didn’t get sucked into all of these secondary roles. I could focus on my primary contribution: the help material. But not having involvement in other aspects of the project, such as the design, testing, interface, planning, and so on, made it harder to write help. I was often a latecomer to information, finding out at the last minute about upcoming releases and stumbling into new pages with changed functionality.

Sitting with my colleagues is heavenly. We understand our kind. We engage in heated debates about style controversies, and sometimes crack jokes about how bad interface text is. We ask each other questions about Author-it and Camtasia. One of my colleagues even brings in peaches to share, and has his own candy store. It’s comfortable to sit with them, and share in the camaraderie.

But in the larger scope of agile development, this isolation from the project conversations that are happening on an ongoing basis seems to have negative consequences. The isolation away from other writers, as I sit near developers and other IT members, might be worth it for the end result. The problem is that projects are often short durations, so I would need to be nomadic for the model to work, moving from one project group to another as my project load shifted.

Perhaps nomadism would be ideal for help authors. When working on project X, sit next to project X. When working on project Y, sit next to project Y. And yet, even despite the improbability of such an open seating model, it seems archaic in a day of virtual collaboration and remotely located workforces. Why insist that maximum productivity is only gained by rubbing elbows with your team all day long? Surely asynchronous methods of communication, real-time online interactions, and regular meetings using VoIP or the telephone can compete with the benefits of nearby seating.

Alternatives to the Dilemma

Despite the logic of embedding myself with a project team, where very likely I’m the only technical writer present, I’m not ready to give up our new-found team momentum. We’re making a lot of progress towards standards and tools, processes and styles. Once the dust settles, we may return to our former model in which we’re embedded in project teams.

Still, perhaps I’m holding out for another reason: I’m not convinced that proximity is essential to keeping up with project information. I’m not persuaded that there aren’t equally viable ways to gather the same data and interact, because if nothing else, the Internet has shown us how remotely distributed people can be closely connected with each other. The Internet has pulled us loose from our physical relationships, distancing us from those immediately around us and drawing us closer to others whom we never see or speak with. Email, instant messaging, Internet Relay Chat, webinars, podcasts, blogs, websites, text messages — all of this enables communication to take place despite physical boundaries. Theoretically, proximity shouldn’t be a problem. But teams who already enjoy proximity have no need for virtual communication tools, so outsiders often feel the need to participate in close proximity model to keep in loop.

It’s true that proximity does lend itself to more immediate updates. When you’re sitting next to a developer and he makes a shout of joy when he gets something to work, you’re updated. When you’re sitting next to a tester who groans each time she finds another bug, you’re updated (that is, if you ask what the commotion is about).

But it’s still possible to stay updated sitting remotely, away from project teams. And this is precisely because nearly every team in most IT groups uses some form of bug tracking tool, such as JIRA, Team Foundation Server, Fogbugz, or something else. Nearly everything gets logged somewhere, and if we take the time to stay close to it, to follow it as carefully as we might read a novel, tracking comment threads, attending meetings, reviewing sprint plans and roadmaps, checking IRC logs, design and requirements documents, listening each day to scrums — if we did all this, we could circumvent the proximity problem and perhaps even stay more aware than team members in the same cube aisle. That is, as long as distance doesn’t deafen our ears, make us forget our priorities and workloads, and lull us into a false belief that nothing much is going on.

Blog Sponsors

Page Layout and Design Tips from Jean-luc Doumont’s Trees, maps, and theorems

Tom Johnson — Thu, 25 Jun 2009 13:55:54 +0000

Trees, maps, and theorems, by Jean-luc Duomont

I’m currently reading Trees, maps, and theorems: Effective communication for rational minds, a new book by Jean-luc Doumont. The reason I wanted to read the book is for Jean-luc’s expertise in visual design and page layout, because I thought it could help me design better quick reference guides. Although very little of the book deals with design and is more geared toward engineers (the “rational minds”), he does address page layout and intuitive design in a couple of sections. Here are a few passages of advice:

“Leave more distance between unrelated items than between related ones.” For example, headings should be close to the text they belong to, rather than equidistant between the last section and the new section. (This principle is termed proximity in Robin William’s Non-Designers Design book.)
“Be visually consistent: format identical items identically, similar items similarly, different items differently.” This helps the reader understand and predict the relationships between the various information units at a glance.
“To indicate hierarchy, display more prominently those items that rank higher or that are more important.” Again, in other circles, this would be the principle of contrast.
“Make sure that each page guides the readers visually along a useful reading sequence or, alternatively, that it gives a clear picture of possible entry points.” This principle is especially important. A document without a clear focal point for readers can lead to a confusing design, such that you look at it and you’re not sure where to begin because you’re eye is drawn everywhere and nowhere (p.73).

Jean-luc’s book has a unique page layout itself. The format is large-print (hence the excessive cost of the book, $99). Each section is usually contained in one bifold spread (by that I mean across two full pages). But you read each spread from right to left. Two columns are on each page. The right column on the right page contains a general explanation of a principle. The left column on the right page contains a minimal graphic. The right column on the left page contains more practical application of the information. And the left column on the left page contains Q&A about the topic. Here are a few sample pages. It’s a weird structure, I have to say. There isn’t much flow from page to page, and I’m not used to reading from right to left. Still, it is consistent.

In “Achieving simplicity and harmony” (p.75), Jean Luc argues that with formatting, writers should use “a healthy dose of self-restraint” instead of indulging in the many layout possibilities that desktop publishing software offers. He recommends black for type color and white space as a principle means of adding contrast. “To make a piece of text stand out,” he says, “just set it apart: increase its distance from other items, thus surrounding it with space.”

Jean-luc also recommends using a single type-face with a couple of type sizes rather than multiple type faces: “Select faces within one family, as these were designed to work well together” (p.74). And he encourages left alignment of the text, with other objects below it aligned along the same left edge. You should only make the decision to justify the text if you prefer a more formal look and if the text blocks “align nicely with the other items on the page” (p.74).

Here I have to pause and make a small comment about a strange, almost OCD quality of the book. Every paragraph of Jean-luc’s book not only has justified text, but the last line of each paragraph ends perfectly justified as well, so that each paragraph is an exact rectangle, but there isn’t much extra spacing between the words at all. At times the content seems to have been written to fill a perfect block form. He doesn’t address this preference of his, but I remember some discussion about it at a presentation he gave at the STC Summit a few years ago.

As for color, he recommends minimalism as well: “Unless you master color design, use few colors, perhaps just one (besides black) in a few tints. Design the page in black and white first, then apply color in touches wherever it adds value” (p. 72). His book’s design illustrates this principle. Drop caps are orange, graphics are grey with a tint of orange, the sidebar is shaded gray, and everything else is regular black, with ample space in the margins.

Finally, he recommends avoiding underlining, bold formatting (within paragraphs), uppercase, and unusual fonts. Overall, Jean Luc is a design minimalist, preferring few colors and fonts and a consistent, simple page design.

As for the question of whether to design the layout before or after writing your content, Jean-luc says, “Logically, a text must have been drafted before it can be formatted, so drafting appears before formatting …. Still, the format might pre-exist or be designed before the text is drafted. Layout constraints, as on the length of texts, should be identified early, so the texts can be optimized accordingly” (p.72). In other words, you write before you apply format and design. However, it’s a good idea to know the constraints of your design before you start writing.

That’s about the extent of the discussion on document design. (He does have a lot to say about the structure and organization of content, such as putting your conclusions first and providing a table of contents, but that wasn’t my primary interest.) Overall, Jean-luc feels that advanced page layout, with multiple colors and font faces and a complex structure, more often than not comes across as amateur and conveys “visual cacophony” rather than an appealing layout. He prefers to minimize the “signal to noise ratio” by adding as little ink to the page as possible to thereby increase the focus on the content.

In buying the book, I failed to realize that I don’t fit the category of “rational minds.” The book should really be titled something like “Structure, diagrams, and reports: writing principles for engineering and science students.” The trees, maps, and theorems part is merely a cute way of saying this, or referring to hierarchy, table of contents, and conclusions. Most of the advice in the book addresses the situation of the engineer, who must write reports, give presentations, include charts and graphics, and create other engineering documents. It is not for people creating help materials, although there is occasional overlap.

Some sections are particularly geared towards engineers. Talking about charts, Jean-luc says “a slope (a ratio of two variations) is more accurate viewed as a direct linear representation of the first derivative” (p.129). Derivatives? Reminds me of calculus classes I took years ago.

Talking about the idea number for lists, he writes, “Four is a square (2²): it is a combination of two binary options. Four is therefore a useful number of answers for rating scales (++/+/-/–), as it embodies a cascade of two binary choices: first, is it rather positive or negative; next, is it a little or a lot” (p.21). Huh? Are we talking about bulleted and numbered lists or quantum mechanics?

Given the engineering audience, one can’t hope for too much style and flair in the prose, but it reads like a college textbook, outlining basic principles in a flat way. It is too focused on “clarity, accuracy, correctness, etc.” (p.79) to make for a fun or engaging read. The start and stop motion of each bifold spread may make it accessible at any entry point, but it also gives you no lure to move from one section to another.

However, if you happen to be teaching a class on writing for engineers and scientists, this book might be just what you need.