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. 23rd we had our 5th Twitter chat, hosted on the @DevEdBookClub Twitter account about Chapter 5.
This post is a recap of the chat and a place to continue the conversation.
Code Samples
What docs or learning platforms have particularly good code samples?
What do you like about them?
Megan Sullivan showed us an example of the Gatsby docs. She liked that the Gatsby docs would include in a code sample the name of the file where the changes should go
Sarah Rainsberger shared a link to the GraphQL tutorials on Apollo Odyssey.
She said:
“I love seeing code WRITTEN out, with arrows pointing to stuff bc its what I do to learn”
How do you like to learn?
Do you have any favorite learning platforms and if so, why do you like them?
Preferred Workflow
What’s your workflow for creating code samples?
At what point in the writing process do you add them?
What tools do you use?
Do you prefer static or interactive code samples?
Ramón Huidobro shared that they like to prepare code samples along with the structure.
Megan and I both agreed it depended on what we were writing. If I write tutorials I like to have a code sample written out before writing.
Do you have a preferred workflow?
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?
dvkr's favorite quote was “It’s better to write looking forward than backward”. When writing code samples we should be sure we are not making it even harder for learners by adding references or examples that need shared perspective to understand.
Ramón shared their favorite quote: “Explanations that accompany your samples are as important as the samples themselves”.
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 5 of Docs for Developers?
Top comments (0)