Why is it essential to establish a clear documentation workflow? How can developers, project managers (PMs), and techwriters work closely together without being a bottleneck? You may be familiar with these issues or looking for a better solution to make the customer and internal (in-house) documentation workflows more efficient.
The development of our workflow spanned about 4 to 5 years, during which we achieved smaller goals and had to adjust our plans along the way.
The actual implementation took 3 to 6 months, but this is surely not its final form. Our work environment and industry are always changing, so we need to keep experimenting to adapt quickly. Now, after reflecting on our progress and making adjustments, we've brought everything together in a more organized way. Even though we had the components ready, it still took a lot of effort to complete the whole picture.
In our technical writing webinar, we delved into the intricacies of techwriting, team dynamics, and project management from various aspects. We are grateful to those who attended and all the questions they asked in the Q&A session. In this blog post, we will recap what we covered (issues and solutions), and publish the answers to the audience's questions.
Table of contents:
- Customer documentation
- Internal documentation
- How to avoid falling behind
- Documentation workflow from planning to publishing
- Takeaways
- Questions and responses from the Q&A session
- Why didn't we show numbers in the estimates?
- How do you ensure you have time for focus time, housekeeping tasks, etc.?
- What do you do when you have excited engineers but few writers to work with them?
- I have the process established in Confluence, but some engineers would like to switch to docs as code. Any advice on that? I don't know where to start?
- Webinar recording
- Resources
We examine bridging the gaps from three aspects: Personal, Technological, and Workflow aspects in the context of customer and internal documentation.
Customer documentation
In our context, customer documentation is the user guide of the custom built Zero Gravity Developer Portal instances Pronovix developed and the results of other technical writing services we provide to our clients.
Personal aspects
Issues
- The Technical Writing team had huge communication gaps with the development teams.
- The boundaries and responsibilities of the techwriters in the delivery process were unclear.
- The team ended up in silos and piled up documentation debts.
Solutions
- Join the calls of the development teams.
- Start to gather feedback.
- Recognize the need for change; establish clearer processes, and trigger a company-wide cultural shift.
- Be proactive and willing to take action.
Technological aspects
Issue
The technical writing team used different tools for task management than the rest of the company.
Solution
Find a common platform to increase transparency and to keep tasks tracked.
'It doesn't matter which system you choose, just make sure it's the same as what others are using in the company and that you make the most out of it.'
'Keep an eye on tasks and make sure everything is on track.'
Workflow aspects
For a techwriter, documentation is the most important deliverable, while for other team members, it’s just one of many. It is our responsibility to highlight the value of documentation. Act quickly: Integrate documentation better into the work of the development teams.
Issues
- Documentation was part of the delivery process but not as a top priority. It did not follow the development, and it became outdated.
- The technical writing team failed to recognize the need for change in time, presuming that adherence to the "original" workflow would seamlessly integrate with the system.
Solutions
- Have a clear documentation workflow and create documentation plans.
- Keep track of your backlog and groom your tickets regularly: make sure that tasks have owners.
- Use a checklist to make progress tracking easier to follow.
- Keep the workload evenly distributed if possible.
- Attend meetings regularly with PMs and the development teams.
- Grant access to essential assets for all stakeholders taking part in the process.
- Avoid double booking.
Internal documentation
In our context, internal documents are installation and setup guides, developer docs, and collections of clearly detailed processes for internal use regarding operations, security, etc.
Why is internal documentation important?
Among others, it’s for
- sharing knowledge,
- helping new team members,
- keeping things consistent,
- encouraging collaboration,
- setting clear rules for making and updating docs.
Personal aspects
Issues
- Hard to find common ground with developers.
- Developers did not know the techwriters were there to support their work.
- Not enough contributors.
- Internal documentation didn’t have dedicated owners.
Solutions
- Monitor communication channels actively.
- Read all the internal documentation (or at least know where to find what), and assure developers about your support. Thus you can help them to find the documentation they need and build trust.
Technological aspects
Issues
- Outdated documentation platform without a search option.
- No easy way to contribute.
Solutions
- Follow the docs-as-code approach.
- Provide direct ways to request changes and edit the content.
- Provide search options.
- Implement feedback mechanisms.
Workflow aspects
Issue
Docs-as-code was challenging for non-technical colleagues.
Solutions
- Create templates.
- Make it possible for others to create new documentation using their preferred tools.
- Help with the formatting.
- Create placeholder pages on the publication platform with links to drafts in Google documents.
- Take ownership over the documents: make sure you have to review and approve every change.
- Create a style guide.
- Document the ways of contribution.
- Educate your colleagues.
'Make documentation part of your work routine, use tools that help writing and updating docs faster, and encourage everyone to share what they know, and help make docs better.'
How to avoid falling behind
- Create a dedicated communication channel only for internal documentation-related discussions.
- Integrate an entry point to the backlog directly into the channel. Provide a solution to raise tickets directly from the channel.
- Create a bot channel to notify you if a ticket is created and when the ticket’s status has changed.
Documentation workflow from planning to publishing
It is important to have a clear documentation workflow, which covers the lifecycle of your documentation from the planning phase to publishing and maintenance. In the following, we’ll give you some insights about what the documentation workflow looks like at the Pronovix technical writing team.
1. Planning
In the planning phase, we collect all the resources we can, ask the PMs to create tickets for us, conduct recorded interviews with SMEs, do estimations, etc. We record all the essential information in a Documentation plan sheet. Having all this information in one place instead of several files makes administration easier and saves us time.
2. Drafting & Writing
Create drafts based on the information on the related issue ticket, the knowledge collected during testing the features, and the interview recording. Use tools and environments you prefer: Google Docs, plain text editor, etc.
Conducting interviews with subject matter experts (SMEs) is an essential part of drafting. Book a timeslot in the SME’s calendar and let them know the details of the call you set up, (and assure them that you are flexible regarding the call), prepare your questions, and record the session. Collect as many resources as you can. When you have all the necessary information and get into context, start writing: first a draft, then the actual section or chapter based on the draft.
3. Reviewing
Use tools that make the documentation accessible for other team members. If you have an accessible tool, you can make collaboration easier: for those members who can only check the result, and don’t have access to Git or other platforms we use, we are often drafting and reviewing in Google Docs, creating a PDF version, or publishing the documentation to a staging environment.
4. Publishing
This is the time of the final review: check the published content on the live environment and look for functional errors and typos.
5. Iterating
Schedule review rounds; they should happen even if the project did not receive updates during the given period of time. In summary, we encountered difficulties on personal, technological, and workflow fronts. However, we tackled these challenges head-on, finding our team members supportive of change and receptive to fresh ideas. Although we're still experimenting, the future looks bright. Together, with a focus on adaptability and progress, we're set for success moving forward. The issues discussed in this blog post are not limited to our internal and client documentation processes or the technical writing services we provide; we have all been there.
If we sparked your interest in our services, do not hesitate to reach out for a free discovery call!
Takeaways
- Share information across teams.
- Learn how other teams work.
- Use the same platforms as other teams.
- Improve estimation accuracy.
- Build relationships with developers.
- Simplify contribution processes.
- Automate error detection and review processes.
- Conduct regular documentation reviews.
- Highlight the importance of documentation efforts.
Questions and responses from the Q&A session
Why didn't we show numbers in the estimates?
Because we assume that different teams estimate differently – some count in hours, others in workdays. We wanted to show the task sizes and how we start measuring them. We mentioned that exact delivery times depend on many things, so we left out specific numbers. Hopefully, this part of the presentation still made sense and was helpful to some attendees.
How do you ensure you have time for focus time, housekeeping tasks, etc.?
Managing tasks and meetings can be tough. At Pronovix, we've got two days a week called "Go, create!" days which we can use for focused work. The general rule of thumb is to avoid scheduling meetings unrelated to your current task on these days. If you have a blocker that needs to be released, you can jump on a call with the SMEs.
To deal with meetings piling up, and to make room for focused work, we plan ahead. Even if it's just for the next two days, we mark down specific times in our calendars for tasks. This helps us stay focused and make progress, even if we can't finish everything.
We also find it helpful to set tasks for the whole day. That way, if we can't finish them, they automatically roll over to the next day as a reminder. But we're flexible, too – if something urgent comes up, we're ready to reschedule.
It's important to set boundaries too. We don't need to tackle every task right away. We check deadlines and, if possible, bring tasks up in our next meeting and add them to our backlog until then. Keeping our backlog organized helps us save time.
What do you do when you have excited engineers but few writers to work with them?
Having developers who are excited about writing documentation is a real gift. At Pronovix, we're fortunate to have developers who excel at writing documentation. This initially made it challenging for us to become involved.
If your team doesn't have enough time to handle all the documentation tasks, it's a good idea to let your developers do it. What we do is edit their docs directly, fixing any minor mistakes and making sure they follow our style guide. This way, they don't have to worry about these small changes, and they appreciate our help.
We also suggest ways to improve the structure and link related documents. This allows us to be part of the documentation process and learn more about what's being documented and where it's stored. Later on, when you have more time, you can build on what the developers have already done with your help.
Creating a guide to help contributors understand their choices and letting them use their favorite tools is important. You can gather information from them and then organize it correctly later on.
I have the process established in Confluence, but some engineers would like to switch to docs as code. Any advice on that? I don't know where to start?
Transitioning from a platform like Confluence to a docs-as-code setup is quite a challenge and requires careful planning.
One big hurdle is that certain features from Confluence, like visuals and building blocks, need to be re-created if you want to keep them after the switch. That's why it's crucial to pick the right platform from the get-go. This could be a static site generator like Docusaurus or Gatsby, or a CMS, like Drupal, or another platform that suits your company's needs. Each option has its own quirks that you'll need to work into your content.
Once you've chosen a platform, take the time to understand what it can do. If there's something you liked in Confluence but your new platform doesn't have it, you might need to get developers involved to add it or find a workaround.
Once you're familiar with the platform, you can start moving your content over. There are tools to help you export from Confluence to Markdown (if Markdown will be your preferred documentation format), but be prepared for a lot of manual work. This transition period is also a good opportunity to set up automatic checks to keep your content consistent. If you want to dive deeper into this topic, feel free to get in touch with us. We'd love to chat more about it.
Webinar recording
Resources
- CIDM: Estimating Documentation Projects
- Tyner Blain: Estimating the Effort of Documenting an As-Is Process
- How to estimate a task? — Story Points Best Practices
- How To Estimate Time For Technical Writing Projects?
- How and why to estimate writing efforts
- Estimating Effort for Technical Writing Projects
- Developing Documentation Style Guide: Basics
- Write More, Chase Less: Project Management for Technical Writers
- What does a technical writer do
- What is technical communication in technical writing
- 7 challenges in technical writing and how to overcome them
- The Joy of Docs, or, Technical Writing for Developers and Engineers
- Content, Collaboration, Community – What You Get When You Invest Non-docs Time in Docs Tools
- The Journey of Our Documentation Platform to Station
- Feedback cycles and their role in improving overall developer experiences
- Understanding Documentation as Product
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
