Stuff

Essentials

  • February 2017
    S M T W T F S
    « Sep    
     1234
    567891011
    12131415161718
    19202122232425
    262728  
  • Facebook

Posts Tagged "documentation"

How can technical writers thrive in agile environments? Event recording and details

Audio Recording

Listen to the recording:

You can download the MP3 file, subscribe in iTunes, or listen with Stitcher.

Agile panel event description

Here’s a description of the agile panel event:

How can technical writers can thrive in agile environments?

Most engineers in IT departments follow an agile scrum process: they track issues in sprints, assign and scope story points, meet daily to provide short updates on their work, and release updates every 2-3 weeks.

Technical writers who work with engineers usually find that being productive requires them to become familiar with the engineer’s agile scrum workflow. Whether you want to keep abreast of engineering work, factor in time for doc reviews during the sprint, or have documentation be managed like other IT work, you need to know how to integrate or work with the agile scrum workflow.

In this chapter meeting, we will have a panel discussion about how technical writers can thrive in agile environments. (See the STC SV event post for more details.)

Tip: If you’re new to agile and scrum, check out Jeff Sutherland’s book Scrum.

Panelists

The following 5 people were panelists:

Bonnie Clark has almost 20 years of experience in the technical communication field. She is currently a Director of Technical Publications at FICO, a leading analytics software company.

Rosemary Picado is the Documentation Team Lead at Sumo Logic, and works with agile and non-agile teams within the company to document their cloud-based log management platform. Formerly at Recommind, she transitioned from Tech Writer to Scrum Master while the platform was being re-architected, learning the value of Agile first hand, and how the skill sets intersect and complement each other.

Daniel Doornbos has been a technical communicator since 1982. He most recently worked as a Senior Technical Writer at HEAT Software on its IT Service Management product. The company is in the process of transitioning to agile development.

Jane Wilson leads the technical writing team for GE Digital’s Applications Engineering group. GE Digital develops in an Agile environment, and, as the team has grown, she has developed processes for fitting writers and the writing process into Agile methodologies. Along the way, she became a certified scrum master. Jane belongs to the East Bay and Atlanta chapters, and she currently serves on the STC Board as Treasurer.

Gina Blednyh is a Staff Technical Writer at Salesforce. She’s worked in an Agile environment for almost six years. She’s also been a scrum master for both a writing team and an engineering team and is an Agile convert.

I moderated the panel.

Questions discussed

Here are some of the questions about agile and tech comm that we discussed:

  • Should documentation be managed as items in an engineering sprint?
  • Should doc reviews be assigned story points?
  • Do you still create a documentation plan at the project kickoff if you are following an agile scrum process?
  • How can you keep pace in documenting features during the sprint if the features don’t get finished until the end of the sprint?
  • How can you reduce the tedium of daily standups when engineers seem to rattle on endlessly about coding issues?
  • How can you stay updated about JIRA items when engineers don’t take the time to articulate the issue but rather hastily add a quick title that only they and other engineers who are already familiar with the issue understand?
  • How can you persuade engineers to dedicate time for doc reviews if there’s no points allocated for the work in the sprint?
  • Logging bugs changes the role tech writers play on teams. Should tech writers log bugs when they find them, or simply send emails to the QA engineers to log the bugs?
  • What processes should tech writers follow in order to publish rapidly during the two-week cycles, especially when tech writers have several projects at once, all of which have two-week release cadences?
  • How can technical writers be valuable participants in the agile process when they are part of 3+ different teams, each of which has its own daily standups, sprint planning, and retrospective meetings?
  • Agile teams often follow a “fail quickly” approach that leads to coding in a lot of different directions in order to find something that works in the market. How can you avoid massive revisions of your documentation with each major direction during this highly volatile period of coding?
  • Agile teams often want to minimize the amount of documentation in order to stay agile and flexible (the principle is “working software over comprehensive documentation”). How do technical writers negotiate the de-valuation of documentation on agile teams (even if the docs mostly refer to project documentation instead of user documentation)? How does minimalism factor into agile practices?
  • What time management techniques can you implement to be more efficient in order to meet the fast-paced demands of agile teams? What can you ignore or cut out of your day? Are all meetings necessary to attend in order to convey the importance of your role on the team?

Share your experience

If you want to share your experiences with agile, you can do so in the comments on this post.

Recording of Let’s Tell a Story — Scenario-Based Documentation, by Matt Ness (STC Silicon Valley Presentation)

Presentation description

Here’s the description of Matt Ness’ presentation, “Let’s Tell a Story: Scenario-Based Documentation”:

To new users, complex software products can seem like dark woods on a stormy day. As tech writers, we often spend a lot of time talking about the overall shape of the forest and the variety of paths within it (conceptual docs), creating detailed catalogs of local tree species (reference docs), and providing step-by-step guides to things like “how to cross a river” or “how to knock on a door” (task-based docs).

But none of that helps your customers when they just want to know how to get to Grandmother’s house, without getting lost in the forest, falling into the river, and accidentally going to the other cabin in the woods, where the lycanthropic senior citizens live.

In other words, your customers need a narrative. And maybe they need lots of them. When you’re dealing with products that can be run and configured in a bewildering variety of ways, a single getting started manual might not do the trick. It’s like giving people a Choose Your Own Adventure book and only allowing them to choose one path through to the end.

For my talk I’ll explain how we became aware of the need for better scenario-based documentation, and how we ended up building a prototype during a hack week project. Now we’re on our way to creating a collection of short stories that show users how to string sets of features and procedures together to solve complex problems. We’ll cover some of the things we’ve learned along the way and offer best practices for those who want to tell a few stories of their own. (Read more details at STC Silicon Valley chapter)

Video

You can watch a video of the recording here:

Audio

If you just want the audio, here it is:

Listen to this post:

You can download the MP3 file or subscribe in iTunes.

Slides

You can view the slides here:

Let’s Tell A Story: Scenario-Based Documentation from Matt Ness

About Matt Ness

Matt Ness is a technical writer with over twenty years of experience at places like PeopleSoft, Oracle, and Intuit. He’s currently a writer for Splunk, a leader in the machine data analytics sector.

Review of Andrew Etter’s ebook on Modern Technical Writing

Listen to this post:

You can download the MP3 file or subscribe in iTunes.

Background

Recently to try to get better sleep, I switched from reading my iPhone at night to a Kindle E-reader. It turns out I really like reading from the Kindle E-reader, so much that I actually bought two of them (the Paperwhite and the Voyager). Reading from the Kindle feels more offline, so I can get immersed more fully in the content, rather than flipping back and forth between email, Reddit, Twitter, or other sites.

While reading on my Kindle, I stumbled across a book called Modern Technical Writing: An Introduction to Software Documentation, by Andrew Etter, published in 2016. It’s is actually a short book (10,000 words), and you can read it about a half hour.

Modern Technical Writing, by Andrew Etter
Modern Technical Writing, by Andrew Etter

Who is Andrew Etter? He provides almost no biographical details about himself in the book, but based on my Linkedin search, he seems to be a lead writer at Palantir, which is a company in the Bay area that I actually toured when I moved out here.

Andrew’s book should be required reading for every technical writer, both experienced and novice. I’ve never felt more at home reading a tech comm book than I have with Modern Technical Writing.

Admittedly the book is short, but this is good. It means he doesn’t pad it with extra fluff to achieve a book-length word count. He jumps straight to the point and writes with such an easy-to-follow, conversational voice that I couldn’t help but just like the guy.

What does it mean to do “modern” technical writing? From a technical angle, Etter argues that one should embrace lightweight markup languages, use static site generators, and store content in version control repositories with engineering code. Etter also argues that writers should spend most of their time researching and testing content, investigating analytics, and iterating on the doc content on their websites.

Contributors and lightweight markup languages

With regards to documentation formats, Etter writes:

… one of the tenets of modern technical writing is that everyone is a contributor. Storing content directly in XML-based languages like XHTML, DocBook, and DITA dramatically reduces people’s ability to contribute…. Rather than being mere deterrents (like writing in XML), specialized applications actually prevent people from contributing. Amazing text editors are available on every operating system, mostly for free, and writers can use whichever they like. … For documentation, lightweight markup is free and superior in every meaningful way.

Etter compares a simple passage in written in AsciiDoc with the same passage in Docbook. The Docbook passage is about about 7 times longer than the AsciiDoc passage and contains so many nested tags it’s nearly unreadable.

Rather than embrace the lightweight formats for simplicity, Etter says technical writers need to encourage contributions from those who have deep, helpful product knowledge. He says,

The reality of the profession is that even a large team of writers cannot possibly know everything worth knowing about an application, and most companies do not have a large technical writing team. The open-source software movement, mod scene in PC games, and birth of a million obscure wikis have proven that people will happily share their expertise and passion if an easy, hospitable way of doing so exists.

Static site generators

Etter also advocates using static site generators for documentation platforms, especially Sphinx because it has built-in search and sidebar navigation. Etter devotes a good part of the book to static site generators, explaining:

I have perhaps an irrational bias towards static websites. I love them. I love their speed, simplicity, portability, and security. You can host static websites practically anywhere…. They have no server-side application dependencies, no databases, and nothing to install, so migrating the entire site is as easy as moving a directory.

Websites instead of PDF

Etter also discourages spending time generating PDFs. With PDFs, users inevitably save the PDF files to their computers, and then rely on them even when the PDFs are out of date. In contrast, by publishing to a website, you can continually iterate on your content and make updates to correct misinformation or add missed content. Etter says,

I mentioned earlier that you should build and host a website, not distribute PDFs, but it bears repeating. Even the best documentation, like software, eventually goes out of date. PDFs get downloaded onto hard drives and then sit there like day-old bagels, growing more and more stale until they’re actively harmful. You can never update them. … The whole situation gives me the chills. Hosting your content on a website gives you the power to fix inaccuracies almost instantly and keep your content in sync with the latest software releases.

Etter perfectly captures all the complaints I’ve voiced about PDFs in so many posts. Reading this, I felt like cheering and celebrating inside. His message is clear: Modern technical writers do not spend time writing and publishing lengthy PDFs, because people prefer to go online for more up-to-date information.

I should note that, as the book’s subtitle indicates (“An Introduction to Software Documentation”), Etter is focusing on the software industry, which is an easier use case for dismissing PDF.

Version control systems

It should come as no surprise that along with using lightweight markup languages like AsciiDoc and Markdown, static site generators, and building websites instead of PDFs, Etter also recommends using distributed version control systems, such as Git or Bitbucket, to store documentation. Etter writes,

If you have the opportunity to store your documentation in the same repository as its corresponding product source code, strongly consider doing so. The approach has some real appeal:

  • Documentation and code branches stay in sync.
  • Developers are more likely to contribute if they don’t have to clone a separate repository.

Etter compares Git with Bitbucket, as well as interacting with these repositories through GUI clients and the command line. Etter also says that if it makes sense, you should also store your doc content in the same repository as the code, since it reduces documentation drift and encourages contribution.

How to spend your time

Beyond a discussion of tools and workflows, Etter offers some advice for writing good content. He says,

… producing content that people will read and find useful is, like, really hard.

Instead of writing all day, Etter says technical writers should spend 90% of their day learning (through testing and research), and only 10% writing. You write only after you have a good understanding of how the system works.

In a section called “Don’t Write,” Etter explains:

Technical writers, first and foremost, are testers and researchers. Your job is to know what people want to achieve and precisely how to achieve it. Communicating that knowledge is the last step of the process and really shouldn’t comprise more than 10% of your time.

Figuring out what to write does require a lot of time and effort. But it’s not so much figuring out how something works as much as determining what information is relevant to users. In a sea of possible product information, what do users actually need or want to know?

Grinding out knowledge

Finally, Etter says,

Technical writers need to be grinders, willing to slowly but surely chip away at the block of ignorance until a beautiful sculpture emerges – or something like that, anyway.

Little by little, one procedural step at a time, we chip away at ignorance and build a body of useful documentation that users find helpful.

Conclusion

In a concise 10,000 word ebook, Etter articulates a unified approach that provides an alternative to the XML + Component Content Management System approach that is so commonly advanced in tech comm circles. To summarize, this approach includes the following:

  • Lightweight markup languages
  • Static site generators
  • Integration with engineering code
  • Contributions from experts
  • Storage in distributed version control systems
  • Testing and researching more than writing
  • Websites instead of PDFs
  • Constant iteration and updating of content

We have far too many books espousing the benefits of XML and championing component content management systems as the model for contemporary tech comm solutions. These models seem outdated and part of another era, one that will eventually be replaced by this lightweight, more flexible, developer-centric approach towards documentation.

For now this modern model seem more applicable to small teams and companies, particularly with developer documentation, but who’s to say that the model won’t grow to fit large-scale teams and companies as well.

Where to get the book

You can read Modern Technical Writing here on Kindle. If you have a Kindle Unlimited subscription, it’s free. (If not, it’s $3.99.)

By the way, if you’re thinking of buying a Kindle E-Reader, I recommend the Kindle Paperwhite).

If you don’t have a Kindle, there are a lot of Kindle reading apps you can use on your smartphone or even the cloud.

Back to Top | Comments Off on Review of Andrew Etter’s ebook on Modern Technical Writing

Other Stuff