Coffee and Content webinar recording: Treat Code Like Code; Treat Prose Like Prose
Video recording now available
Coffee and Content webinar details
Here’s the Coffee and Content webinar description:
Treat Code Like Code; Treat Prose Like Prose
Join us for a Coffee and Content chat with Tom Johnson about what it means to “treat code like code and prose like prose.” In the docs-as-code tools space, a popular method for reviewing docs is to review docs using the same code review tools that software engineers use to review code. Code review tools cater to engineering workflows and preferences, for sure. If you want an engineer to review a change in your docs, it makes sense to use the same review method the engineer is accustomed to using for reviewing code.
However, good docs require input from people outside of engineering roles. Product managers, field engineers, quality assurance, support engineers, legal advisors, UX, and other stakeholders also need to review docs. A review process that excludes these non-engineering roles can be problematic, especially since these other roles often serve as a check and balance against the features engineering teams create. Sometimes it’s better to treat docs more like prose instead of code.
Date: Sept 24, 2020
Time: 8:00am PST
Channel: BrightTALK
Cost: Free
Registration: You can register here.
Background
This topic came about after I wrote a post called Treat code like code and prose like prose. I think this post falsely gave the impression that I was somehow abandoning the docs-as-code workflow, when in fact I was just pushing back on code review tools as a primary form of doc review given that code review tools cater almost exclusively to engineers. My point was that a good review process is more inclusive of other roles (such as PMs and field engineers). A code review for doc changes might still be appropriate to target engineer reviewers, or as part of a formal release process.
Discussion topics
Possible questions/topics for this webinar include the following:
- What does docs-like-code mean?
- Why do writers in this space often use code review tools to review docs?
- What did your dev doc survey find about the popularity of using code review tools?
- What’s required to get your docs into a code review tool?
- What are the advantages of reviewing docs like this? What visibility and rapport does this give you with other engineers?
- What are some of the disadvantages of reviewing docs like this?
- Is there a danger of excluding non-engineering roles in the review process?
- Why can’t they just use the code review tools to review content?
- Do we sometimes over-index on treating docs too much like code? Is content development (prose) unique from code development? In what way do they differ?
- What does it mean to treat prose like prose and code like code?
- What is the ideal review process for docs?
- How do you port content from a collaborative system where many reviewers feel comfortable leaving comments back into your documentation tool?
- What were the results of your survey regarding what others think of treating code like code and prose like prose?
- What other tips do you have for getting others to review documentation?
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.