Cover photo by Chris J. Davis on Unsplash
We started a book club! Each week, we host a Twitter chat on Thursdays to discuss a chapter of Docs for Developers.
On Thursday Dec. 9th, we had our third Twitter chat, hosted on the @DevEdBookClub Twitter account about Chapter 3, Drafting Documentation.
This post is a recap of the chat and a place to continue the conversation.
Writing Process
What does your writing process typically look like? How do you get from idea to first draft?
What practices does your organization have around templatizing your docs?
How do you prioritize your work if you need to write multiple docs at once?
Several of us identified with Sarah Rainsberger's tendency to hold onto an idea until it all spills straight out into a draft.
Sarah Rainsberger@sarah11918
@meganesulli @DevEdBookClub I often find that I make an outline AFTER I have draft pieces, to make sure everything is covered. But I often feel like the draft comes first, then it's checked against all the things that usually help people get started.
#DevEdBookClub02:17 AM - 10 Dec 2021
It turns out that this practice is actually described in a writing lecture given by Larry EcEnerney at the University of Chicago!
You are using your writing process to help yourself think.
dvkr@_dvkr@sarah11918 @meganesulli @DevEdBookClub I felt a lot better about doing this after watching this video. Granted the advice is geared towards academic writing, but there was a lot that I took away. Your point about an outline AFTER the draft is one of the first things he mentions! #DevEdBookClub youtu.be/vtIzMaLkCaM02:25 AM - 10 Dec 2021
Portia Burton described her own process for figuring out what the docs should say.
Portia 🚢@agencycecil@DevEdBookClub A1. I get clear on what task I want the docs to accomplish.
I sniff around the target audience's hangouts to gauge
a. What do they already know about this topic?
b. What are the common problems?
c. How are folks solving this problem now?
Then I write my draft. #DevEdBookClub02:31 AM - 10 Dec 2021
Her approach ties in well with the theme of writing empathetically that we discussed in the previous week.
Writer's Block
How do you get unstuck when you have writer’s block?
What’s usually the thing blocking you?
Several folks mentioned that they're usually blocked by a lack of knowledge (or confidence in their knowledge) of the subject. Amber Matz shared how she tackles that feeling.
Amber Matz@amberhimesmatz@DevEdBookClub A2) When I have writer's block on a tutorial, it's usually because I don't feel sufficiently comfortable with the material, which leads to a bit of imposter syndrome. I ask colleagues, watch conference talks, or dive into the code to get unstuck. #DevEdBookClub02:28 AM - 10 Dec 2021
I like to say what I'm thinking out loud to focus my thoughts on a topic and to get past the point of staring at a blank page.
A2) I use speech to text when I’m feeling stuck on a writing project! I do this for articles, talks, sometimes even tough emails. It helps me to get everything out there on the page and then I can clean it up later. It also helps me to phrase things more naturally. #DevEdBookClub02:33 AM - 10 Dec 2021
It works really well for me and my answer to this question seems to have inspired some to try it for themselves. Remember, though, that the best writing process is the one that works for you!
Sarah Rainsberger@sarah11918@AishaBlake I always think this should help, but wonder whether being a fast touch typist keeps me feeling more comfortable when I'm keyboard-bound. It's like, "words just go into the air..." as if I'm afraid they're escaping?? But, I can type them just as fast & they're THERE.02:53 AM - 10 Dec 2021
Favorite Takeaways
What takeaways from this chapter can you apply to your own documentation practice at work?
Any quotes or ideas that resonate with you?
Megan shared the following quote and how the paradox it describes is reason for us to care in everything we write because we can't know which part will resonate with someone.
@DevEdBookClub A3) I loved this quote:
There are two fundamental, paradoxical truths about readers of technical documentation:
• Readers come to your documentation looking for information.
• Readers read very little of what you write.
#DevEdBookClub02:45 AM - 10 Dec 2021
Join the Conversation 🗣
You can see the full conversation on the DevEdBookClub Twitter account.
DevEdBookClub@devedbookclubWelcome to our 3rd #DevEdBookClub!
Tonight, we’ll be discussing Chapter 3 of @DocsForDevs. This chapter is all about writing the first draft of your documentation.02:00 AM - 10 Dec 2021
Add a comment on the Twitter thread or share your thoughts here to continue the conversation.
What did you think about Chapter 3 of Docs for Developers?
Top comments (0)