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. 30th we had our 6th Twitter chat, hosted on the @DevEdBookClub Twitter account about Chapter 6.
This post is a recap of the chat and a place to continue the conversation.
Visual Content
What docs have particularly good examples of visual content?
What do you like about them?
Megan Sullivan pointed to Vue’s documentation and this flow chart in particular as a good example of visual content.
@DevEdBookClub A1) I really like this flowchart in the Vue docs. It clearly lays out all the steps for a really technical process, and it looks pretty!
vuejs.org/v2/guide/insta…02:05 AM - 31 Dec 2021
Portia mentioned Julia Evan’s programming zines called Wizard Zines. They use visuals to cover a variety of topics like Bash, Networking, and Linux.
Portia 🚢@agencycecil
02:40 AM - 31 Dec 2021
Dvkr gave a shout out to the comics that are found in React’s new beta documentation. They enjoy how the comics personify React.
Aisha Blake said she liked Plaid’s documentation because of the illustrations that help her visualize the use of their product. They combine the visuals with helpful code examples.
@DevEdBookClub A1) The @Plaid docs have some really lovely illustrations to help visualize how to use their products along with helpful code examples (which we talked about last week)! plaid.com/docs/02:09 AM - 31 Dec 2021
What are your favorite visuals for learning new content?
Creating Visuals
What’s your workflow for creating visual content? At what point in the writing process do you add them?
What tools do you use?
Do you have any questions about creating visual content that this group might be able to help weigh in on?
I shared that my workflow changes depending on the content. Sometimes I start with a visual and create content around it. Other times I leave the visuals for the end. I also mentioned I enjoy using Figma and Affinity designer to create visuals that are SVGs. Some of the visuals I create I like to animate and SVGs make this easier to accomplish.
I use Procreate when creating an image.
@DevEdBookClub A2: This often changes for me. Sometimes I start with a visual and create the rest of the content around it. Other times I save visuals for the end.
I like using Figma, Procreate, or @affinitybyserif
#DevEdBookClub02:28 AM - 31 Dec 2021
Valeria uses online white boards like Weje to manage multiple projects and visualize their workflow.
Valeria@vlrmigova@DevEdBookClub Q2) I love to use online whiteboard Weje. It allows to manage multiple projects and visualize a workload in easy way. Also It suits perfectly for brainstorming, creating mood boards, kanban boards, teamworking.05:25 AM - 31 Dec 2021
Aisha and Portia both admitted they have a hard time creating visual content. Aisha likes to commission illustrations when possible. Portia tries to draw something on paper first and then uses tools like Miro.
@DevEdBookClub A2) I’m not great at communicating visually, if I’m being honest. I generally leave this til the end, when I know exactly what I’m trying to say. Often, it’s just screenshots but I’ll sometimes commission illustrations.
#DevEdBookClub02:31 AM - 31 Dec 2021
Portia 🚢@agencycecil@DevEdBookClub Q2) I'm VERY bad at this and I'm trying to improve. I draw something on paper first and then I use tools like app.diagrams.net and miro. #DevEdBookClub02:52 AM - 31 Dec 2021
Do you have a preferred workflow? What tools do you like to use to create visuals for your documentation?
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?
Sarah Rainsberger had two favorite takeaways. First, she liked the message “Simplify to Amplify". Visuals can be really helpful but can also be very distracting.
Sarah Rainsberger@sarah11918@DevEdBookClub A3. I liked the message "Simplify to Amplify" because it's true, visuals can be great, but can just as easily be a distracting mess if not as edited/focused as our prose. #DevEdBookClub03:11 AM - 31 Dec 2021
Second, she appreciated the reminder that screenshots aren’t always the best option. They lack text for screen readers. Use in your documentation only when they are the best option.
Sarah Rainsberger@sarah11918@DevEdBookClub @DevEdBookClub A3. And, I liked the reminder that a screenshot is great, but the text isn't available for copying that way, so pick WHEN a screenshot really is the best tool. (That said, where's the font where inner brackets ARE SMALLER, like I can hand write??) #DevEdBookClub03:17 AM - 31 Dec 2021
Portia added she would have liked a section in the book that talked about maintaining visuals. A lot of documentation sites struggle with keeping their visuals up-to-date.
Portia 🚢@agencycecil@DevEdBookClub Q3) I wish there was a section on maintaining visuals. Many companies struggle to keep their screenshots and diagrams up-to-date. #DevEdBookClub02:59 AM - 31 Dec 2021
Join the Conversation 🗣
You can see the full conversation on the DevEdBookClub Twitter account.
DevEdBookClub@devedbookclubWelcome to our 6th #DevEdBookClub!
Tonight, we’ll be discussing Chapter 6 of @DocsForDevs. This chapter is all about adding visual content.02:00 AM - 31 Dec 2021
Add a comment on the Twitter thread or share your thoughts here to continue the conversation.
What did you think about Chapter 6 of Docs for Developers?
Top comments (0)