This content originally appeared on DEV Community and was authored by Christina Gorton
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.
Sarah Rainsberger@sarah11918
@DevEdBookClub A1: I found the specific distinction between "Tutorial" and "How to Guide" interesting! (The focus on learning, with a provided environment/data/example vs focus on guiding the user through building on their *own* project, in their own environment.) #DevEdBookClub02:04 AM - 03 Dec 2021
@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.
rstav@rmstav@DevEdBookClub A1 I was surprised by code comments as a content type, but it makes sense. It veers a little bit towards “good code documents itself,” but if used carefully, comments aid understanding, especially for newer devs.
#DevEdBookclub02:07 AM - 03 Dec 2021
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.
Sean C Davis@seancdavis29A1) At @stackbit we're working through the process of overhauling our docs site. The most surprising and difficult part of the journey has been the READMEs.
I didn't even think about them at first. We have so many repos. It's a whole other thing to manage.
#DevEdBookClub02:08 AM - 03 Dec 2021
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.
@DevEdBookClub A2) Bringing in an expert to help us improve our docs and create a style guide for tone, wording, etc helped us loads.
Having one of these before starting to write in the future is something I'm going to bear in mind moving forward!07:00 AM - 03 Dec 2021
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.
A3) I've already mentioned how much I love a good template! 😂 Reading through this chapter definitely expanded my thinking on what forms of docs can/should potentially be made into templates. IME, the easier you make it to maintain docs, the better for everyone.
#DevEdBookClub02:59 AM - 03 Dec 2021
Megan Sullivan appreciated the reminder to compare your list of planned docs against your user's journey.
@DevEdBookClub A3) I like the suggestion to compare your list of planned docs against your user journey map, to see where the gaps are.
It helps me get back to thinking about things from the reader's perspective. Do they have a clear path from A to Z? Where might they get lost?
#DevEdBookClub02:44 AM - 03 Dec 2021
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.
Sean C Davis@seancdavis29@meganesulli @DevEdBookClub The most important piece of advice I've received is to write empathetically.
To not think about how I would organize or write the docs, but how the user would discover and read them. That's why we're writing them, after all.03:00 AM - 03 Dec 2021
Join the Conversation 🗣
You can see the full conversation on the DevEdBookClub Twitter account.
DevEdBookClub@devedbookclubWelcome to our 2nd #DevEdBookClub!
Tonight, we’ll be discussing Chapter 2 of @DocsForDevs. This chapter is all about planning your documentation.02:00 AM - 03 Dec 2021
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?
This content originally appeared on DEV Community and was authored by Christina Gorton
Christina Gorton | Sciencx (2021-12-06T21:05:25+00:00) Twitter Chat: Chapter 2 Recap. Retrieved from https://www.scien.cx/2021/12/06/twitter-chat-chapter-2-recap/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.