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. 2nd we had our second Twitter chat, hosted on the @DevEdBookClub Twitter account about Chapter 2.
This post is a recap of the chat and a place to continue the conversation.
Content Types
Did any of the types listed surprise you?
What great examples have you seen of a particular content type? What stands out about it?
Sarah Rainsberger mentioned she found the distinction between a “Tutorial” and a “How to Guide” interesting. She liked that the book made these two content types distinct.
@RMStav and myself were both surprised to see code comments mentioned as a content type for documentation. We both mentioned they can be extremely useful and it makes sense to give them a higher priority to help aid developers new to a project.
Which content types do you have the hardest time creating? The easiest? Why?
Many of us agreed that READMEs have been both hard to create and maintain.
Do you manage any of your company's repositories? Do you find the READMEs hard to create or manage?
Planning Strategies and Processes
What strategies or processes have you used in the past to plan your documentation?
What worked well? What would you do differently next time?
What questions do you still have about how to plan documentation?
Ramón Huidobro pointed out that having an expert come in and help create a style guide and improve their docs was a useful strategy for them and something they would continue to do in the future.
What processes or strategies have you used to plan documentation? Were your processes successful?
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?
Aisha Blake enjoys using templates. After reading this chapter she realized there are many more forms of content that she could create good templates for.
Megan Sullivan appreciated the reminder to compare your list of planned docs against your user's journey.
Sean C Davis added that the most important advice they received was to write empathetically. He pointed out that we should always have the user in mind when writing our docs.
Join the Conversation 🗣
You can see the full conversation on the DevEdBookClub Twitter account.
Add a comment on the Twitter thread or share your thoughts here to continue the conversation.
What did you think about Chapter 2 of Docs for Developers?
Top comments (0)