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
@DevEdBookClub A1) Some things I really liked about the code samples in the Gatsby docs:
- They included the name of the file where the changes should go
- They had line highlighting, so you could point readers to exactly which piece of the snippet to pay attention to
#DevEdBookClub02:06 AM - 24 Dec 2021
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”
Sarah Rainsberger@sarah11918
@DevEdBookClub A1. I was really impressed with odyssey.apollographql.com - included some handwritten/annotated code (in addition to a cool code playground/quiz system).
I love seeing code WRITTEN out, with arrows pointing to stuff bc its what I do to learn
#DevEdBookClub02:05 AM - 24 Dec 2021
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.
@DevEdBookClub A2) Most of the time I’ll prepare code samples along with the structure.
Having interactive code samples is always great for trying these out, but it’s for me that they’re easy to copy and then paste!14:31 PM - 24 Dec 2021
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.
@DevEdBookClub A2: I’d say this is dependent on what I’m writing. For tutorials, I often have the code example written out first and that guides what I wrote after. I might change things a bit as I start writing.
#DevEdBookClub02:19 AM - 24 Dec 2021
@DevEdBookClub A2) For me, it depends on what I'm writing.
If it's a tutorial, I usually write code blocks as I'm building out the demo site, so I can remember what steps I followed. (Plus it helps me make sure I don't leave anything out.)
#DevEdBookClub02:18 AM - 24 Dec 2021
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.
dvkr@_dvkr@DevEdBookClub A3) "It’s better to write looking forward than backward." This was re: considering non-trad background devs, and making sure the references and jokes were from a shared context and perspective.
#DevEdBookClub02:47 AM - 24 Dec 2021
Ramón shared their favorite quote: “Explanations that accompany your samples are as important as the samples themselves”.
@DevEdBookClub A3) “Explanations that accompany your samples are as important as the samples themselves”.
It’s so wonderful to have something I’ve always practiced out into words so well!14:33 PM - 24 Dec 2021
Join the Conversation 🗣
You can see the full conversation on the DevEdBookClub Twitter account.
DevEdBookClub@devedbookclubWelcome to our 5th #DevEdBookClub!
Tonight, we’ll be discussing Chapter 5 of @DocsForDevs. This chapter is all about integrating code samples.02:00 AM - 24 Dec 2021
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)