I am back from my very first Write The Docs (WTD) conference in Portland. I represented Cockroach Labs at the Writing Day. We set up our project for open source contributions and the response was amazing! And we were in good company – the other open source Writing Day projects included Kubernetes, Write The Docs, and Netlify. I also met up with Mike Lewis from GitLab and had a productive discussion about their open source contribution process. To summarize, I am pumped up about all things open source docs, and want to share all I learned with you!
Which brings me to an exciting announcement: I am teaming up with Information Developers Foundation to conduct a webinar about “Contributing docs to open source projects”. This is a topic I am passionate about because I have benefited immensely from working with open source projects. But my pet peeve is that while everyone agrees that contributing to open source is a great idea, nobody really talks about how to actually go about it. What is an open source project? How do you get started with one? What do you need to know to make meaningful contributions? What are the things to look out for, or things not to do? I intend to answer all these questions and also walk you through a few open source projects I personally like. So join me on May 19 at 8:30 PM IST to discuss how to contribute to open source projects. Here’s the registration link:
Also, feel free to send in any questions or topic suggestions you might have and I will try to answer them in the webinar:
In April, I had the privilege of sharing with you the day-in-the-life posts from four inspiring technical writers. To wrap up the series, I wanted to do something special. Which is why I made my very first day-in-my-life vlog! Here it is for your viewing pleasure:
Don’t forget to check out the day-in-the-life posts of our amazing guests:
Bart Leahy: Day in the life of a freelance technical writer (who previously worked at NASA and Disney)
Jason Tham: Life of a PhD student in Technical Communication
Swapnil Ogale: Day in the life of a contract technical writer in Australia
Larry Kunz: Day in the life of a technical writing veteran
Special announcement: There will be no post next week because I will be at the Write The Docs conference. However, I am planning to live-tweet the conference. Follow me on Twitter to keep up with the live updates!
The last post in this month’s series of guest posts is by Larry Kunz, a technical writing pro for 39 years! I have been a follower of Larry’s insightful blog for quite some time now, and it is an honor for me to have Larry share his perspective here on my blog. So let’s get to it! Here’s Larry’s post:
I’ve worked in technical writing, and in closely related fields, like project management or marketing, for almost 39 years. Today I’m a Lead Technical Writer at Extreme Networks.
We make and sell equipment for data networks — switches, routers, wireless access points — and the software that controls them. I write the documentation for installing, customizing, and maintaining the physical equipment.
You might’ve heard that technical writing is humdrum, that we do the same work day in and day out. That isn’t my experience.
One of the things I love about working in technical writing, in fact, is that every day is unique. We serve our employers and our customers in so many ways, and we use so many processes and tools, that every day presents new variety.
Let me show you what I mean, by stepping through a day in my life.
Knowing the technology
You might’ve heard that technical writers only need to know the basics of the technologies they work with. That isn’t my experience.
Today I’ll read the design specs for a new product the company hopes to introduce. I’ll read with two purposes in mind: to learn about the product, and to return comments to the designer if anything seems out of whack or is unclear. I might challenge the author to explain the app in terms that a customer would understand — to help me (and the customer I represent) understand how to use the app, not how the app works.
Working on teams
You might’ve heard that technical writing is a solitary profession — that you spend most of the time by yourself. That isn’t my experience.
Today I’ll meet with a software designer to get a big-picture understanding of a new app that customers will use to monitor our equipment. I’ll visit the hardware lab, where one of our test engineers will show me how our new switches are cabled together. In both cases, my colleague will help me gain the understanding I’ll need to describe our products to our customers.
You might’ve heard that technical writers aren’t respected by subject-matter experts, or accepted as colleagues. That isn’t my experience.
Today I’ll meet with three colleagues from Engineering, one from Tech Support, and one from Marketing to discuss a white paper I’m developing. This particular piece was inspired by something a customer wrote on the company’s user forum. It looked so good that I suggested touching it up and publishing it on the company website. But now, questions have arisen about whether its recommendations are in sync with the company’s overall marketing themes. I’m sure we’ll have a lively discussion, with each constituency being heard before I try to lead the group to consensus.
Solving problems creatively
You might’ve heard that technical writing isn’t a creative endeavor. That isn’t my experience.
Today I have to write instructions for mounting switches in a rack, when three different switch models come with three different mounting brackets. Some of the steps will be common to all three models, but some will vary. Making each step clear and not leaving anything out will require cleverness and imagination. It’ll require creativity.
Creativity is the art of solving problems, whether the problem is how to paint the creation of Adam on a curved surface (as it was for Michelangelo) or how to document the best way to mount three switch models with different mounting brackets. Don’t misunderstand: I’m not saying that I have even a tiny fraction of Michelangelo’s genius or talent. But I’m saying that he would recognize the creative process involved in doing the job of a technical writer.
A new day tomorrow
After a day of delving into technical details, of talking – and leading a conversation – with subject-matter experts, of solving problems creatively, I’ll rest up for tomorrow.
Tomorrow’s tasks will be different. I’ll post the final, approved version of a Hardware Configuration Guide. I’ll meet with the team that maintains the Confluence wiki we use to communicate throughout the Tech Pubs organization. Since I hold a senior-level position within my team, I’ll also be helping to rewrite the template our organization uses for documentation plans.
See what I mean? Every day is different. But every day makes use of my technical knowledge, every day has me working on teams, and every day gives me a chance to solve problems creatively.
Is technical writing the life for you?
Today’s post in this month’s series of guest posts is by Swapnil Ogale, a contract technical writer residing in Australia. I follow Swapnil on social media, and find his insights and experiences of the Australian technical writing community interesting and informative. I am so glad he’s here to give us a deeper insight into the Australian Tech Comm culture. Here’s Swapnil’s post:
When Amruta contacted me a couple of weeks back for this guest post, I wasn’t sure how to approach this. As a Technical Writer who contracts, I am often working a couple of jobs most of the days. In addition, I also organise the Write the Docs Australia meetups across a few cities, so I am constantly looking for speakers and thinking of topics that would interest the attendees.
If you are in the fortunate position of working on exciting projects simultaneously, here are some of my experiences on how you could make it work.
The Early Bird
I like starting early (around 5.30am), because the peace and quiet (and a fresh cup of chai) helps me focus into getting a mental list of tasks ready. Often, early in the mornings, I like reading through my Slack channels to get a sense of the conversations that have happened overnight. Some days, it could just be reviewers getting back to me with feedback, whereas some days it could the developers talking about bug fixes or designers prototyping new interfaces.
This short early morning ritual helps me schedule and priortise work for later in the day.
Public transport, social media, opportunities
My workplace (day job) is a 45 min ride and 2 train connections away. I usually catch up on documentation news via Twitter, looking for tips, hints and any other interesting chats around documentation. I also initiated the Write the Docs Australia meetups a couple of years back, so I follow up on potential speakers, conversations and other themes around this.
I also use this time to search for projects needing documentation or potential consulting opportunities and Twitter surprisingly provides a lot of interesting material for this.
At my last workplace, work hours were pretty flexible, and since I was already up early, I got into work before the rest of my team did (around 7.30 am). For the last couple of years, I was documenting processes for a number of internal teams. Process documentation is not unlike product documentation, but it is slightly more chaotic. While product or software documentation is reliant on periodic changes (such as sprints or releases), process documentation is driven by continuous changes to the processes. These changes come about due to refinement or improvement to existing processes.
I spent a few minutes to understand these process changes, compare them with existing processes and update or create new documentation (work instructions, quick reference guides). We used Confluence to create documentation and JIRA and Trello to track our projects.
Plan, design and innovate
Along with process changes, I also spent time looking at our existing documentation and making improvements to make the content more useful, readable and reusable. If there was something that I really needed to focus on without distractions, I use the Pomodoro timer.
If the documentation changes required talking to the engineers or operators, I would set up one-on-one meetings to source this information and/or review the documentation.
Work from home afternoons
The flexibility at work made it possible for me to head home mid-afternoon (for my son’s school bus pick up) and work from home for the afternoon. I would usually schedule any meetings in the afternoon, usually done via Skype.
Spending time away from the desk, also gave me a chance to catch up on emails or requests for changes to the content without any interruptions.
In addition to my regular day job as a Tech Writer, I also work part time on documentation projects remotely. Most nights, I usually work a couple of hours, planning, creating or curating content for software applications. These projects could be local (Australian) or anywhere across US, UK, Europe or Asia.
I currently document online help, release notes and other content for a project management tool for architects and engineering firms.
I use a range of tools to plan (Trello, JIRA, Mindmaps),create (Madcap Flare, Zendesk, Confluence, Google Docs), and curate (JIRA, Slack) for my projects, depending on the customers need and setup.
Working in Australia
Over the last 12 years, I have been lucky to work in some terrific Australian born and bred organisations across a range of industries. A lot of organisations reflect the same kind of multicultural mix that is now a large part of the nation. This provides some great opportunities to work with, understand and collaborate a range of thoughts, ideas and beliefs.
The work culture also largely reflects the core Australian values of mateship, fair go and a sense of integrity. While Technical Writing is not a new concept here, I’ve found, in my contracting experience, that it still not fully understood and lacks the same amount of support from management resultantly. The value of a technical writer or what they bring to the table is still a bit unclear. Also, a large number of companies are still reluctant to support remote working due to various reasons. From my own personal experience, Australia is still a few years behind in catching up with the tools and technologies that can be adopted to make documentation an entirely fulfilling experience, both for the writers and the users alike.
Today’s post in this month’s series of guest posts is by Jason Tham, a graduate student currently pursuing a PhD in Technical Communication at University of Minnesota. I have studied Jason’s articles for the Research Methods in Tech Comm course for my Masters program and followed his academic career via social media. I am so excited you get to hear from him today. Here’s Jason’s post:
Collaboration is at the heart of technical communication, and I see at least two reasons to why that’s so: 1) technical communication materials are produced for human use and therefore always require human input; and 2) as cliche as it may sound, it remains true to me that no one knows everything, but everyone knows something––thus two or more heads are better than one when it comes to solving technical communication issues or tasks.
As a PhD student, my work in the past 4 years has been largely collaborative. Whether in practice or pedagogy, I have been acculturated to working with users, designers, researchers, and teachers. These interactions are often productive and rewarding; they help me create more effective documents, design and perform better studies, and deliver innovative instructions. In this guest post, I share some of my collaborative experiences in research, publishing, teaching, service, and professional practice.
Collaboration in research
After reviewing my CV, I realized more than half of my current projects are shared with other researchers in and out of my home department at my university. While I have worked in larger teams that ranged from four to eight researchers, my typical collaborations are in teams of two (myself and another researcher or scholar). Whether we are co-investigating a common problem or co-authoring a report, my experience with sharing a research project has been rewarding. I have always learned new research methods and strategies for communicating my findings. Furthermore, from a research standpoint, collaboration may boost the validity and reliability of a qualitative study if inter-rater reliability is utilized and achieved.
Collaboration in publishing
When publishing in technical communication journals (or any journal, I suppose), authors tend to work with journal editor(s) to identify the publication’s scope, standards, and other publishing specifications. I consider this interaction with journal editors and even responses to blind reviews as a kind of professional collaboration. Such collaboration ensures the quality of a publication––that authors produce scholarship that advance knowledge, reviewers provide feedback that enhance the scholarly merits of the refereed work, and editors ensure the integrity of the publication is preserved and supervise the production process.
I have also been blessed with the opportunities to co-edit some special issues of technical communication journals––most recently for the Journal of Business and Technical Communication and Computers and Composition––on special topics like “design thinking approaches for technical communication” and “immersive technologies and writing pedagogy.” In these co-editing experiences, I have collaborated with other academics to create calls for papers, review submissions, coordinate peer reviews, and work with authors and publishers. Special issue publications such as these tend to require a kind of collaborative dynamic that’s different from a regular journal issue as we had to draw resources from a select pool of experts and work within a specific publication timeline that complements the publisher’s workflow.
Collaboration in teaching
Based on my teaching experience, students find it more meaningful to work with problems that have tangible impact on their lives and those around them. As an instructor of technical communication, this means I need to work to bridge theory and practice in student learning. To achieve this goal, I have been collaborating with faculty members with other disciplinary expertise to co-design course modules and learning activities that benefit students in our classes. For instance, in the current (Spring 2018) semester, I am teaming up with a professor from mechanical engineering to create a learning unit for my business writing course where my students serve as press release writing consultants to graduate engineering students whom they are partnered with. This collaborative effort gives both my students and the graduate engineers in another course an opportunity to cross path and learn from each other.
Collaboration in service
As a member of the technical communication discipline, I am also called to provide services to the field that advance its visibility and wellbeing. In my opinion, these services are best done through collective effort and thus I have collaborated with other graduate students and scholars to co-organize events that led to the aforementioned goals. One example is the 21st Annual Great Plains Alliance for Computers and Writing Conference, where three active scholars in my department and I co-hosted in the Fall of 2017. Pulling together a regional conference isn’t a task that can be easily accomplished by an individual; by collaborating with colleagues and other graduate students, we were able to co-design a program that reflected the trends of the field and attracted presenters that had interesting topics to share.
Collaboration in professional practice
When not teaching or conducting research studies, I work as a leasing agent for a student housing provider. Collaboration is ingrained into my work routine; more often than not, I am working with other fellow agents to address leasing and marketing needs––we review our weekly leasing (sales) performance, discuss existing customer service issues, and come up with solutions to address these situations collaboratively. Also, part of my work is dedicated to maintaining a shared database of resident profiles and incoming prospects. Every leasing agent at my property plays a part in keeping shared notes and updating the database. Each year, it takes a team of six leasing agents, working very closely with a leasing manager, to fully lease our residence. While leasing and customer service may not be directly related to technical communication, they are communicative activities that require similar professional rigor.
Together, all these experiences help me grow as a technical communicator, whether through research, publishing, teaching, service, or professional practice. Indeed, as my academic advisor––Dr. Ann Hill Duin––wrote with her collaborator more than 25 years ago, collaboration in technical communication is a research continuum, rather than a static phenomenon or theory. The motivation and techniques for collaboration in technical settings keep shifting according to the context within which the collaboration occurs. My advice for rising technical communicators is to dip their toes in multiple collaborative contexts as part of their training so they may be hone their skills in collaborating with others.
Contact: Jason Tham, email@example.com
Since January 2018, I have been blogging thrice a week about pursuing a Masters in Technical Communication, being a Technical Writer, and becoming “more technical”. However, all the posts were based solely on my experience, thereby providing only my limited perspective about the field of technical communication. I wanted to know more about others’ experiences and provide diverse perspectives on the blog. So I invited the technical communicators that I have admired and learned from over the years, to share their experiences on this blog, and they accepted my invitation!
Hence in April, I am tuning down the frequency of my posts from thrice a week to once a week to focus the spotlight on our guest bloggers each week. Here’s the schedule:
April 4: Bart Leahy – Former technical writer at NASA and Disney, currently freelancing. In his post, Bart gives us a sneak peek into the day-in-the-life of a freelancer juggling multiple projects.
April 11: Jason Tham – A student pursuing a Ph.D. in Technical Communication. In his post, Jason gives us an insight into the collaborative projects in technical communication across academia, service, research, and publishing.
April 18: Swapnil Ogale – A technical writer in Australia, Swapnil shares a day in his life as a contract technical writer in Australia.
April 25: Larry Kunz – A veteran technical writer with 30 years of experience, he is a treasurehouse of knowledge!
I am so excited to share their knowledge and insights with you! Stay tuned and don’t forget to subscribe.
After last week’s post about Docs FixIt Day at Cockroach Labs, I received several requests asking me to suggest open source projects that people can contribute docs to. As far as I know, almost all open source projects accept docs contributions. The following list includes some open source projects I find interesting:
- Mermaid (Docs: https://github.com/mermaidjs/mermaidjs.github.io)
- Typo 3 Documentation
- OpenStack Docs
- Microsoft Docs
If you have any favorite docs-friendly open source projects, tell me about them in the comments. And don’t forget to subscribe!
Update 1: Suggestions from the community:
Update 2: Came across this article: Open Source Maintainers Owe You Nothing, which I thought was a mandatory read for anyone who wants to contribute to open source projects. It is important to remember that developers and maintainers of open source projects usually work on these projects on their own time and dime, and it is not their responsibility to help us understand how the project works. We need to put in our own efforts, read all available documentation, learn about the project on our own, before we ask for their help.
This week, I interrupt your regularly scheduled programming of technical writing techniques to brag about the incredible people I work with, who exemplify a company-wide culture of good documentation.
Let me give you some context: As most of you know, I work as a Senior Technical Writer at Cockroach Labs. For a major product release coming up in April, we had around 163 open issues to be documented for the release. Some of the issues were big-ticket items while a considerable number of issues were small but time-consuming fixes. It wasn’t humanly possible for our team of 4 technical writers to document all the issues before April. While brainstorming possible strategies to complete the documentation tasks, we thought of enlisting the help of our fellow Roachers* to contribute to our docs. The Engineering team had previously organized a successful Bugs FixIt Day, so we decided to replicate their model and announced a Docs FixIt Day.
We planned and prepped for days – announcing the Docs FixIt Day at the weekly team meeting, sorting through the issues and marking the ones we thought the engineers can take up, and of course arranging for snacks. Our fearless leader, Jesse Seldess, brought delicious Babka, and my fellow tech writer, Lauren, baked out-of-the-world, drool-worthy cookies.
We started the day with Jesse’s “Getting Started with Docs” presentation. He discussed the purpose of the FixIt Day, walked the engineers through the Docs toolset (GitHub and Jekyll), and announced the prizes – a Docs-team authored poem** and an Amazon gift card. The prizes would be given to the person who resolved the most Docs issues, and also to the person who resolved the Docs issue with the biggest impact.
We had 24 people in attendance for the kickoff session – in office as well as remotely. At the start of the day, we had 83 open issues marked as FixItDay. The participants included interns, engineers, engineering managers, and our CEO as well! They self-assigned the issues they wanted to work on and wrote docs all through the day till 6 PM. The last I checked on the day, we had 52 open PRs ! And people were contributing PRs even after that, so the final count might have been higher. (IMO, Jesse deserves an award for reviewing all the PRs).
To say the day was a success is an understatement. Not only did we get a big chunk of our documentation done, but the event also fostered cross-functional team collaboration. The engineers’ enthusiasm was infectious – they were totally invested and involved in the whole Docs process. We had given them the option of either working on the Docs end-to-end (as in they write, edit, revise the content), or just provide the raw content and the Docs team takes over the PR for them. But almost all engineers opted to complete the docs themselves, asking us for assistance with our GitHub process and SQL diagram generators and so on. This gave them a chance to understand the Docs toolset and they voluntarily helped us figure out how we can optimize the toolchain.
I have never been prouder to be a part of a company as I am now. As a technical writer, I am intensely aware of how big of an anomaly our company culture is. In most companies, docs are added as an afterthought and technical writers are considered a pesky annoyance. At Cockroach Labs, however, the importance of good, sound documentation is deeply ingrained in our DNA. And that is evident in all forms of documentation we produce – RFCs, user docs, training materials, or even meeting notes. That is also evident from the fact that we already have a team of 4 technical writers for a team of around 35-40 engineers, when it is not unheard of at other companies to have one technical writer for 120 engineers. It is a privilege to work at a company where people genuinely care about good documentation and are willing to do everything they can to ensure we maintain the quality documentation we have. And I am thankful to be a part of an immensely talented team that is rooted in our core values: “Aim High and Build to Last”.
You can check out the awesome work our team did for Docs FixIt Day here.
*Roachers n. People who work at Cockroach Labs
**Poems written to express our appreciation for our peers is a time-honored tradition at Cockroach Labs.
As an engineer-turned-tech writer, I have repeatedly heard “Writing is so hard; how do you do it?” and “Anyone can write”. Both statements are fallacious. Yes, anyone can write, but not everyone can write well. And yes, writing is hard, and it is made harder by the romanticized notions of inspiration striking, wooden cabins in the middle of nowhere, and solitude.
In reality, writing is a methodical, multi-step process. In this blog post, I attempt to break down my technical writing process so as to demystify it and hopefully make you think about your own process. The following image depicts my writing workflow for any technical document:
As the image shows, my writing workflow consists of four phases:
Phase One: Research
My research phase consists of the following steps.
- Use the Cornell Note-taking System to briefly record the key points gathered from sources (reading materials, talking to engineers, attending meetings, and so on).
- Use the Feynman technique to ensure that you understand the information.
- Setup CockroachDB.
- Try out the feature being written about.
Phase Two: Draft
I use the 5-draft method while writing documents.
Phase Three: Editing and Reviews
Once I am satisfied with the rough draft, I edit my document using several techniques. Each technique helps uncover and correct different facets of the document:
- Grammarly: Check spelling, grammar, adherence to technical writing conventions
- Text-to-speech: I use the text-to-speech feature on my Macbook Pro to listen to the document. It helps me catch awkward sentence constructions, missing words, and so on.
- Elements of Style: This little book sits on my desk and reminds me of my personal pitfalls/repeated mistakes. I have earmarked the style guidelines that I know I forget. Going through the book helps me ensure I am not repeating my mistakes.
- Style guide: I go through the company style guide to ensure I adhered to it.
Once I am done self-editing, I open a Pull Request in GitHub which enables others to review my document. My review process is iterative, wherein my draft goes through technical and editorial reviews multiple times before it can be published. At Cockroach Labs, our engineers and other stakeholders (Product Managers, Sales, etc.) review the document for technical accuracy and completeness, and my manager and fellow technical writers review the document for editorial as well as technical completeness and correctness. The perks of working at a company that is deeply interested in good documentation 🙂
Phase Four: Publish
Once the reviews are done and everyone gives the LGTM (Looks Good To Me), it’s time to merge the document on GitHub and celebrate! Check out my Git profile here.
Try out the process, form your own, and share it with me at firstname.lastname@example.org. And don’t forget to subscribe!
Bonus: I track the various phases of each document in my bullet journal: