If you registered for this event, please log in into your QCon Plus account.

Session

Automating Writing Technical Documentation

Many developers complain that writing documentation takes them out of their flow state. 

Documentation code reviews work better when teams use a linter for their documentation- just like they would use for their code. There’s less arguing about syntax and style when the style guide has been automated via GitHub actions and vale. If they can’t pass the tests, then they can’t merge their docs into master.

In this talk, developers will learn how they can automate their technical documentation process and create a culture that embraces up-to-date and well-written documentation. 

Main Takeaways

1 Hear about the need to write code documentation, why it is helpful and how it can be done.

2 Learn how to automate writing documentation, what are some of the tools to use, and how to work with style guides.


What is the work that you're doing today?

I empower companies by attracting paying technical stakeholders. My company is called Document-Write. We do documentation and we also do content writing, content marketing for tech companies. I worked as a software developer for many years, but I'm also interested in entrepreneurship. And it didn't seem like a whole lot of avenues for technical people to be able to create sustainable businesses without one putting out a tip jar, which is not sustainable for most people, or begging for money, which is again not attainable for most people. What I've noticed during these conversations is that for many developers who want to start businesses, it's very much a conversation of lack or what they don't have, and what they do have is content and what they can use. Is this content as a way to educate people about the framework of their product and use that education to help people make informed decisions about using your product. That's what I'm doing. Content marketing. Writing uses many other arenas for a way to acquire client customers, but you don't really see it in the open source or the tech world. And so not only do I help companies create useful documentation, but I also show them the different ways that that documentation can help financially sustain their organization.

Do you write the documentation for them or do you get the process started and help them?

We do all of the above. We do consulting. We do content audits, which we look at the content that the companies already have. We see what's not working, we see what is working, and we give suggestions. We also write documentation from the ground up. And for some companies, they do have documentation, but they have a really hard time keeping it up to date or making sure that the writing is inviting. And this actually ties into what my talk is about. That's when we introduce automation. Many of these common problems are out of date documentation or documentation that sounds like an engineer wrote. It can be solved by using tools. It's really getting your technical writers adopting a doctor's code philosophy where they're using Git, and so Git is a great way to see who wrote which sections. It's also a great way to show when the documentation was last updated. In terms of voice and making the documentation more inviting to read, there are things called style guides. Style guide is basically you give the guide to a person and from the style guide they know which adverbs to use, which verbs to use. It's almost like a design guide but for writing. And it's a really hard thing to be able to make sure that everyone's using the style guide, and that's why during the presentation I will be talking about style guide linter. It's just like in JavaScript or Python, when you use a linter you want to make sure that you don't have arguments about semicolons, not semicolons. If you already have the rules there, it's just automatically implemented so that a person knows exactly what kind of stylistic mistakes that they're making and how to improve.

What are your goals for the talk?

I want people to feel empowered to use GitHub actions to overcome their excuses for poor documentation. I want the next time their documentation is out of date to come up with a solution for dealing with that problem. I want the problem of, Hey, we don't like how our documentation sounds or it doesn't have a good tone to it. Instead of just shrugging and saying, Well, we don't know how to solve that issue, they'll be empowered to know what exactly is a style guide and how they can use a style guide in their linter and how they can install this linter using GitHub actions.

Is there a difference between public-facing documentation and internal documentation?

I'm glad you brought it up. Internal documentation, I would argue, really deals with the issue of culture and efficiency. So I spent a lot of time on Twitter, maybe too much time and every so often you hear these debates about the 10x engineer. Who is a 10x engineer? Where do you find a 10x engineer? And I think that's the wrong way of thinking about it. What you should have is 10x processes. You should have documentation that turns normal developers into 10x engineers. And like I said before, a huge part of having those processes in place is documentation, making sure things are clear and making sure that you can confidently onboard new developers so not only are they able to carry out the task, but they also are able to carry out the task with confidence. Plus, it really deals with that three boss problem that we talked about a lot. I've been on teams where all the knowledge is in one engineer's head, and that's fine until they go on vacation, and then they're in a cabin, there's no Wi-Fi and all that documentation and all that knowledge and that institutional know-how is lost. So being able to not be so dependent on one developer and I probably shouldn't say this, but it's also gets back to culture issues in terms of if everyone's writing documentation, then you're not going to be in a situation where you don't want to fire a developer or let go of a developer for not doing well in other arenas. I've seen situations where developers were kept on because they had all of this knowledge in their head and it wasn't shared in documentation.


Speaker

Portia Burton

Owner of Document-Write

Portia Burton is the owner of Document Write, a technical content agency for software companies. She specializes in creating engaging tutorials and automating the documentation process.  Before Document Write, Portia worked as a community engineer at Protocol Labs, and a software developer...

Read more
Find Portia Burton at:

Date

Tuesday Nov 2 / 11:10AM PDT (40 minutes)

Track

Becoming a Better Developer

Topics

DocumentationDeveloper ExperienceDevelopmentAutomationTechnical DebtProgramming

Add to Calendar

Add to calendar

Share

From the same track

Session Developer Experience

Analyzing Codebases for Fun and Profit

Tuesday Nov 2 / 09:10AM PDT

One problem existing for many developers today is ramping up quickly complex and sometimes messy codebases. Analyzing domains is an important skill when we need to solve complex problems, take ownership, contribute to open source, break down monoliths, or even perform code reviews in unknown...

Jordan Bragg

Architect @CastlightHealth

Session Developer Experience

Talk Like a Suit: Making a Business Case for Engineering Work

Tuesday Nov 2 / 10:10AM PDT

We all know the feeling. We see these scary problems in our code and architecture, we raise our concerns, leadership nods their head encouragingly, but every planning session and backlog grooming, only features show up on the list. You think, well, I guess we'll have to wait for something...

David Van Couvering

Senior Principal Architect @eBay

PANEL DISCUSSION Developer Experience

Becoming a Better Developer Panel

Tuesday Nov 2 / 12:10PM PDT

In this panel, we'll discuss ways to improve as developers. Are better tools the solution or can simple changes in mindset help be a more effective developer as well as a better team player? And what practices are already here but not yet universally adopted? 

Jordan Bragg

Architect @CastlightHealth

Portia Burton

Owner of Document-Write

David Van Couvering

Senior Principal Architect @eBay

View full Schedule

Less than

2

weeks until QCon Plus Nov 2021

Level-up on the emerging software trends and practices you need to know about.

Deep-dive with world-class software leaders at QCon Plus (Nov 1-12, 2021).

Save your spot for $799 before November 12th

Register