Listen to the recording:
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.)
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.
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.
Ferry Vermeulen from Instructiv asked more than 70 technical writing professionals (from conferences such as Lavacon, MadWorld, COMtecnica, ETC, tekom Berlin, Nordic TechKom, and Information Energy) the following question:
If you could use just three technical writing tools in your company, which ones should you use (in the technical writing tools definition, standards and other helpful attributes are included)? (See Technical Writing Tools: The Ultimate Expert Choice.)
Of course if you ask people at Madworld, a technical writing conference focused on Madcap Software products, what their favorite tools are, they’re going to include Flare and other Madcap products, so just keep that in mind.
However, the mix of professionals from European conferences like Tekom (a large TC conference in Germany) and Lavacon, which isn’t focused on any specific tool but rather leans toward content management and content strategy, provides more of a well-rounded mixup.
Highlighting a Few Responses
Looking through the responses, I’d never heard of IEC 82079-1:2012, which Ferry describes as “The international standard for User Instructions.” (Even looking at the link, it’s still vague to me.) Solidworks Composer looks like a good tool for documenting machinery graphics that require exploded 3D images.
George Bina mentioned Schematron, which looks useful if you use oXygen XML Editor.
Some people avoid listing technical tools and instead list conceptual “tools” or theories, such as minimalism principles, structured technical writing (DITA), usability testing and task analysis, cross-industry thinking, “Not to apply our mental model for that of the user,” and “my brain.”
It’s clear for some, they work in more high-level strategies and concepts and probably don’t always perform the tactical, nitty-gritty execution. That or they’re just tool agnostic.
Joe Gollner listed Github as an essential tool, as did some others. Lukasz Gornicki says Github is “hosting that enables … whole new ways of generating and hosting documentation content.”
Qian Li listed Microsoft Lync (an instant messenger client) as an essential tool. Eric Reiss listed Skype.
Andrew Lawless listed Termweb, a terminology management solution.
Magda Caloian listed “Writing on Post-Its” as well as “Books (exactly, real books).” (I’m wondering which books. Are we talking fiction, style guides, or industry books such as those reviewed in the TC Journal?)
Marc Achtelig listed Freemind, a mind-mapping tool.
A good UX tool is priceless. Something like Verify to collaborate and test UI layouts helps build data-driven decision in design. Too often there is contention around untested opinions. A philosophy of research, good practices/methods, with a tool to support the process can align cross-functional team members to create a positive user experience.
Andrea Maliska listed Sketch and Sabine Stoye noted Inkscape. Maliska says she likes Sketch “for wire-framing and building out mock ups for UX and design.” It’s “lighter than having to learn photoshop.” She also listed Trello, which allows you to organize your projects using cards. Hmmm, Trello. I’ve heard of this tool quite a bit. Maybe it’s time to try it out?
Various people (mostly Europeans) listed quite a few XML-based CCMSs that I’ve never heard of.
Sarah O’Keefe listed structured content, terminology, and automation (defined as “tasks where humans don’t add significant value”).
Eric Reiss made this comment about tools:
To be perfectly honest, I’m not sure it really matters which tools one uses when working with UX in general and usability specifically. First of all, the tools change and evolve regularly, so what may be a good tool today can easily be replaced by something better at any time. Second, a tool is never better than the person using it; just buying, for example, Camtasia Studio from TechSmith for screen recording (which is a very solid and widely used suite of products) will not make the quality of your work better.
Good points! Still, at some point in the execution of a strategy, you have to open up a tool of some kind.
Anthony Apodaca listed Omnifocus, which is a kind of productivity smartphone app.
Lukasz Gornicki listed “Documentation Continuous Delivery” as a tool. He describes this approach as follows:
It is about having a solution that allows you to easily scale the content delivery process across an organisation without the need for any special on boarding. It is about enabling delivery development teams to provide as much content as often as they need with just one click. I’ve presented it at a few conferences already: https://github.com/derberg/documentation-continuous-delivery. This year I talk more specifically about the approach and its usage with Microservices infrastructure and will present the tooling for it that we are open sourcing before the end of this month.
Gornicki is one of the few tech comm pros to list static site generators in his toolset. I was hoping to see more docs-like-code responses in the responses. There were quite a few people who listed Github (often with DITA complements), so this suggests some trends at least.
Andrei Essaoulov made an interesting comment, essentially highlighting the shortcoming of tools to handle all the needed situations:
As a note, what I bump against a lot recently is the necessity to manage collaboration on content created in different tools: As an API writer I need developer input, I need engineers to write, but they prefer to write Wiki or markdown. I also get input from support and marketing, and they are Word users. So, if I were to create a perfect collaboration environment, it would allow Wiki, and maybe form-based technical writing; it would have markdown/ASCIIDoc capabilities; and also efficiently ingest Word into some kind of XML-based backend CMS. I feel like whoever comes up with that will corner the tech comm technical writing tools market.
Overall, Ferry’s post provides an interesting lens on the tools that tech comm professionals use. If you’re looking for a tool to do something, you might browse this list. This list of tools also shows you the diversity and variety of tools that people in our profession find indispensable.
With the modern online documentation tools like ClickHelp, you can create Web Help output as well generate PDF, DOCX, EPUB and other formats from the same source. Start your own documentation portal today: get ClickHelp trial. Get your ClickHelp.co trial today and give it a try.
James Gill invited me to contribute responses to a questionnaire about a typical day in the life in my career for the upcoming second edition of his book, How to Get Started As a Technical Writer. This section will appear in a chapter that discusses the real-world work life of technical writers in different industries and specializations.
James is expecting to publish this second edition book in the next month. On the book details page, you can sign up to be notified when it’s available. As a way to help promote the book and build excitement for its upcoming release, James allowed me to publish my questionnaire here.
You can view more details about the book here: How to Get Started As a Technical Writer
Here are my responses to the questionnaire:
What is your current title?
Senior technical writer
How long have you been a technical writer?
About 11 years.
What are the companies you’ve worked for like?
As a technical writer, I have always worked in companies that develop software. The companies vary in size and their culture, but mostly the innovation originates with the engineering group, and that’s where I tend to both interact and get the information I need for documentation.
Some companies in the Bay area provide free food and try to promote a fun, casual atmosphere. For example, when you interview for a tech job in Silicon Valley, you would almost never wear a tie. At some companies, engineers are champions at ping pong and foosball.
I tend to prefer smaller groups (like startups) where I have more autonomy and feel I can make an impact. However, startup environments can be somewhat of a roller coaster ride with hiring and layoffs (which depend on funding and sales), so at times I prefer the stability of an established company.
What was your first technical writing job, and how did you find it?
My first technical writing job was with a financial firm (Raymond James) in Florida, working with a team of about a dozen writers. I found the job through a recruiting agency that was trying to fill the position. At the encouragement of a colleague, I was attempting to transition from a job as a copywriter into technical writing.
To persuade the hiring manager that I had the technical skills required for the role, I learned RoboHelp and put together some sample projects. I also compiled my best copywriting samples into a portfolio.
One of the articles in my portfolio was an article about how protein works, which I’d written as a copywriter for a health and nutrition company. The hiring manager for the tech docs team had a PhD in biology, so she had some knowledge about protein. She was impressed by the writing sample and later told me it was this article that connected with her and got me the job. She felt I had clearly explained a complicated process.
What does a “typical” work day for you look like? Feel free to describe with as much detail as you’d like.
I try to plug into the agile flow of my project team as much as possible. If you’re new to agile, I definitely recommend reading Jeff Sutherland’s book Scrum. It will explain how to integrate with engineers on a software team, since nearly everyone today follows agile/scrum processes to some degree.
In following agile, I look at the items assigned to me for the current sprint (two-week cycle) I’m working on. I like to select three of the tasks and write them on sticky notes that I put at the bottom of my monitor. This helps me focus during the day.
Here are some typical tasks I might work on during a sprint:
- Draft project plan for new project
- Describe REST API endpoint in Swagger spec
- Meet with engineers for explanation of a component
- Update code samples in previous version of doc
- Create architectural diagrams that show a structure and workflow
- Create overview material for a new product
- Draft release notes for new features of a product
- Meet with engineers to review changes to API endpoints
- Create a video tutorial showing a complicated process
- Rewrite poorly written legacy content
- Review instructions an engineer wrote and include them in the documentation
- Troubleshoot errors in PDF outputs
- Create proof of concept for documenting long JSON objects in API requests
In agile, you have a backlog of items that represent the bulk of work in a project, but you don’t try to tackle them all at once, nor do you graph out a projected timeline representing a waterfall that breaks down the exact work you’ll cover for the next six months. Instead, you focus on items you think you can accomplish during a two-week period, and then when the sprint finishes, you demo the work you’ve completed.
At most software companies, hours are flexible, so I can somewhat come and go as I please, but I usually put in about an eight-hour day, arriving at about 8:30am and leaving at around 5:30pm. I take time for lunch, go on a walk, and sometimes read blog articles on breaks. If I’m absorbed in a project, sometimes I’ll work at home, especially if I’m trying to figure out some aspect of a tool or if I’m learning the technical nuts and bolts of a platform or programming language.
My tech writing colleagues are all virtual, with two colleagues in Arizona and one in the UK. We use instant messaging and meeting conferencing tools to interact. It’s okay that we’re not close to each other because it’s more important to be close to the engineering teams building the products we’re documenting. I sit in an open office environment right next to the project manager, quality assurance engineers, and other team members.
All of the doc team members contribute in a Mercurial repository using Jekyll, a static site generator. We’re all using the same project code, pushing and pulling updates, making commits, and interacting within the documentation repository.
What does technical writing look like in the next 5-10 years? How might a person just starting out prepare for such a future?
For the next 5-10 years, there will be a continued proliferation and diversification of tech comm tooling, because it’s getting easier to build and deploy tools. There are many code bases you can leverage to build your own tooling that exactly fits your company’s needs.
I think DITA will continue to grow, particularly lightweight DITA, because there are many component content management systems (CCMS) and other platforms built specifically to parse and process this content. In contrast, many of the more unstructured formats like Markdown don’t allow you to graduate to a larger CCMS to manage it all.
Nevertheless, static site generators and other Markdown-based tools, particularly browser-based tools, will also grow in popularity, though more so for smaller companies and for more technical projects.
API documentation will be the main staple of tech docs, because almost all companies will be producing APIs that allow different clients to integrate the company’s services in custom ways. Technical writers will write primarily for developers using these APIs and other associated tooling, such as SDKs, reference implementations, and other developer platforms.
There will be fewer tech writers focused on instructions for user interfaces (GUI documentation). The content these tech writers do produce will be tightly integrated into the interface itself.
For tech writers to thrive, they will need to know some programming and be in tune with how to write instructions for developers. They will focus on how to integrate code, whether that code involves calls to an API or some other technical implementation.
For API documentation, REST API specifications like Swagger (now OpenAPI) will be the norm and will integrate more fully with other documentation tooling, especially online tooling. These specifications will be parsed by platforms that host and manage documentation. The platforms will read the spec-based documentation and transform it into robust, interactive and sharp looking docs.
Nearly everything, including documentation, will be browser-based SaaS services, so the whole Mac versus PC compatibility issues will fade away.
If tech writers work locally with file-based content, they will publish that content dynamically by simply committing the update to a Github repository, which will trigger a continuous build process on the server where the content is hosted.
What do you like best about technical writing? What do you like least?
I like creating something from nothing. Initially there’s a blank page and a lot of confusion around a product, but then little by little you figure out how it works. You write documentation that gives clear instruction to perform a specific task with the product, and then you document another task, and another. After a while, you have a lot of instructive topics that explain how to use the product.
You start to add some visual polish, such as workflow diagrams, screenshots, and maybe a screencast. You add some step-by-step tutorials, maybe some some interactive features that let users try out endpoints. Before you know it, you’ve got a full-fledged help system that lets people learn and use the product.
This is what makes the career of technical writing so fulfilling — creating something that didn’t exist before, and which consists of highly valuable information (not fluffy marketing copy) that people find useful for learning. This learning empowers them to be better at their jobs and other ambitions.
What is the most difficult part of being a technical writer?
It’s difficult when you’re trapped by legacy tools and outdated processes and can’t change. When you have hundreds or thousands of pages of documentation in an old format, it can take months of tedious, monotonous work to convert it over to a new format.
Persuading your colleagues to use the new tools and format can be equally challenging. And when you have doc for different products that exists across various formats and platforms, with colleagues who aren’t as tech savvy or interested in exploring and experimenting with new systems, it can be tough to push forward.
But little by little, you can change things. It might take more than a year or two to actually implement a new process, but as long as you have good managers and leaders who understand the larger vision and scope of what you’re trying to do, you can be successful in changing these situations.
9. If a person seeking their first technical writing job wanted to get hired onto your team, what are the three most important things you’d tell them to do?
Create a portfolio of persuasive writing samples. Hiring managers want to see that you can write. It’s okay if you’re not writing in simplified technical English or following a particular technical style guide. Teams want to know that you can write clear, flowing sentences with correct grammar, well-organized ideas and other structure that make the content readable.
Develop some interpersonal skills. You’ll need to interact skillfully with engineers and other team members to get information. People want to work with people they like, so learn to listen, ask questions, share information honestly, be friendly, responsible, and so on. People skills can go a long way in selling yourself.
10. If you could give only one piece of advice to your younger self just starting out in technical writing, what would it be?
Don’t trust any instructions that you read. Test everything out yourself. This is particularly important in developer documentation environments where the steps to actually test out the code may be challenging and involve complicated setups.
Without the ability to test content on your own, you’ll rarely create help content that is easy to follow and error free. If you can, try to get in the user’s shoes as much as possible by using the products yourself.