Write the Docs: Almost None to Some: Driving DISQO's Doc Culture as a Solo Documentarian – Falon Darville

Catherine Heath | April 28, 2021

This Write the Docs Portland 2021 talk was given by Falon Darville. She is a private investigator turned technical writer. She’s the sole technical writer at DISQO in Glenville, CA. She determines what documentation they need in the company. She took DISQO from having almost no documentation to having some documentation. This talk outlined the five core strategies Falon used to accomplish that change.

For each strategy, Falon also identified a motto to go with it (as well as writing prompts).

Strategy 1: Finding comfort in incompleteness

Falon has had to learn to find comfort in incompleteness, a strategy that a lot of documentarians of all stripes can likely relate with. The challenge with incompleteness is it's not necessarily a reflection of the work you’ve done. You might have a lack of people resources, or a lack of infrastructure. There might be lack of organizational support for documentation. 

Falon advises trying to remove the pressure you're putting on yourself when documentation is incomplete and minimal by:

• Remind yourself of the limits of your resources, rather than taking it all on as something you might have done wrong

• Give flexibility by offering templates to create documentation faster, but promote case-by-case adaptations of those templates based on individual documents' needs.

• Don't aim for the documentation to be "finished" before you're happy with it; there will always be more work to do.

• Let go of the thought of working toward perfect documentation and embrace this motto:

Motto

I work towards good enough documentation.

Strategy 2: Influence, don’t force

Falon's second strategy is to influence, don’t force. Not all efforts are going to make an impact. This can happen when:

• There's no overt managerial backing

• Documentation is not perceived as critical or having a direct impact on business performance, so it seems like an aside or afterthought. 

Falon advises trying to start influencing friends by:

• Providing immediate value.

• Making your work visible. 

• Going to stand-ups or other engineer meetings.

• Get onto release channels and announce your deployments just like engineers do.

• Create surveys to enable others to share their experience with documentation at your organization.

• Blog about your documentation.

• Lean into others' do-it-yourself mentality and give them information on how to pitch in.

• Give interested people access to create or edit documentation.

• If you use Docs-as-Code approach, have engineers submit merge requests. 

• Keep an open attitude about the quality and quantity of content that engineers pitch in – harsh feedback promotes silence. 

It's not helpful to try to force your coworkers to appreciate documentation. Gently persuading them of documentation's value is the way forward. 

Motto

I empower others to take responsibility for documentation.

Strategy 3: Empower others through onboarding and training

Falon's next strategy is to empower others through onboarding and training. As she designed the architecture of the documentation, she came up with three tenets: 

• Transparency

• Improved communication

• Lower barriers to entry

Onboarding and training of new employees can come in many forms. Concrete steps Falon identified include:

• Showing new employees where documentation is and how it's organized

• Hosting onboarding sessions

• Providing comprehensive technical writing documentation

• Providing technical training for Markdown, Git and terminal to less tech-savvy individuals so they can contribute to Docs-as-Code.

You can't expect new employees to proactively involve themselves with the documentation. You need to make the effort to reach out at an early stage. 

Motto

I guide new employees through documentation.

Strategy 4: Establish key partnerships

Falon also talked about how she established key partnerships with other members of the organization. The challenge of establishing key partnerships was determining who would help in the goal of increasing the volume and quality of documentation. To this end, Falon laid out a few potential steps:

• Single out individuals who are pro-documentation, or at least show the least amount of resistance. They should be curious about the documentation, do their own documenting, and express overt interest in the docs. 

• Find at least one ally per job title in the organization. This could be a software engineer, product manager, and manager.

• Form some kind of group or organization. Falon calls hers the Tech Doc Guild, which is a group of engineers she checks in with to review the documentation efforts going on within their teams. 

Motto

I invite those interested and curious about documentation to be my allies.

Strategy 5: Finding your place in the organization

Finally, Falon encourages you to find your place in the organization as a solo technical writer. It’s critical that you build your own department, even if it’s just you following the rules:

Develop your technical writing style guide and technical writing onboarding documentation. You’ll clarify what you do and it’s a tangible way for you to show others what you do and identify gaps you need to work on in your department. 

Develop your place in the organization by being an active participant in inter- and cross-departmental happenings:

• Reach out when you need interaction. 

• Start a Slack channel on a topic of interest. 

• Attend Zoom events like happy hours and holiday celebrations. 

• Start or join a book club.

Don't limit yourself to only writing documentation – build your own department and take the time to participate in activities outside your job. 

Motto

I have a strong identity within my organization.

Final remarks

We'd strongly recommend this talk if you're a solo writer (or one of only a few writers), though honestly many of her strategies for creating allyship and empowering others translate well into companies with larger writer teams, too. We love this shift in positivity with the mottos to focus making connections, empowering others, and bringing visibility to your efforts.

Watch the full talk here. 

{{snippet.authorCatherineHeath}}

{{snippet.Disqus}}