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.
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
Megan Sullivan@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@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?
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.
Megan Sullivan@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?
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”.
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?