{"id":423,"date":"2022-04-22T10:54:00","date_gmt":"2022-04-22T14:54:00","guid":{"rendered":"https:\/\/redmonk.com\/kfitzpatrick\/?p=423"},"modified":"2022-05-02T10:58:31","modified_gmt":"2022-05-02T14:58:31","slug":"docs-roundup-2-2","status":"publish","type":"post","link":"https:\/\/redmonk.com\/kfitzpatrick\/2022\/04\/22\/docs-roundup-2-2\/","title":{"rendered":"Docs Roundup 2.2"},"content":{"rendered":"

Docs (and tech comm) items of interest<\/a>: docs in two recent \u201cstate of\u201d reports; upcoming Write the Docs conferences; the 2022 ATTW conference; Docs for Developers<\/i>; OSS docs; DevTechDocsOps, are we paying technical writers enough?<\/p>\n

\"Miniature<\/p>\n

The State of Documentation<\/h1>\n

Two recent high-profile \u201cstate of\u201d reports have helped highlight the key role documentation plays in building better software:<\/p>\n

The 2021 Accelerate State of DevOps report<\/a> includes data on documentation practices for the first time in the report\u2019s history (just jump to page 21 for all the documentation goodness). Notably, the report focuses on the internal documentation practices of software teams:<\/p>\n

Good documentation is foundational for successfully implementing DevOps capabilities.<\/p>\n

For the first time, we measured the quality of internal documentation and practices that contribute to this quality. Teams with high quality documentation are better able to implement technical practices and perform better as a whole.<\/p><\/blockquote>\n

The Continuous Delivery Foundation (CDF), one of the sponsors of the report, did a lovely blog post to recap the report<\/a>, and also hosted a follow-up discussion on the report results<\/a> (in which they kindly invited me to participate).<\/p>\n

GitHub\u2019s 2021 State of the Octoverse<\/a> report also makes documentation one of its main topics, with an entire section on Creating documentation to support developers<\/a> consisting of the following topics:<\/p>\n

    \n
  • Critical documentation<\/li>\n
  • Contribution guidelines<\/li>\n
  • README–or not?<\/li>\n
  • Issues as documentation<\/li>\n
  • Good first issues<\/li>\n
  • Docs for productivity and culture<\/li>\n<\/ul>\n

    While the entire docs section is worth a read, the introduction to the \u201cCritical documentation\u201d topic is worth citing in full here (but also check out the charts and data<\/a> in the report).<\/p>\n

    Documentation is critical but often under-invested<\/p>\n

    Documentation is often an under-resourced area of projects, despite being critical to onboarding new contributors, improving the quality of work, and creating shared understanding.<\/p>\n

    What the data shows<\/b>: Sharing and sourcing knowledge through different forms of documentation improves productivity both in open source projects and at work. Internal documentation covered onboarding, governance, tutorials, structure\/dependencies, and best coding practices.<\/p><\/blockquote>\n

    The 2021 State of the Octoverse report also cites the 2021 Accelerate State of DevOps report in its \u201cDocs for productivity and culture\u201d topic:<\/p>\n

    Documentation is good for productivity and culture — it\u2019s a win-win<\/p>\n

    Strong cultures built on trust are supported by good information flow, and recent research by DORA<\/a> shows that quality documentation improves performance.<\/p><\/blockquote>\n

    I love GitHub\u2019s nod to the Accelerate State of DevOps report here, and also the acknowledgement that many folks still refer to it as \u201cthe DORA report\u201d years after Google Cloud acquired DevOps Research and Assessment, LLC<\/a> in 2018. It is also worth noting that Dr. Nicole Forsgren<\/a>, one of cofounders of DORA and co-author of the book that gives the Accelerate report<\/a> its updated name, is currently a partner at Microsoft Research and one of the authors of the 2021 State of the Octoverse report.<\/p>\n

    Upcoming Write the Docs Conferences<\/h1>\n

    Write the Docs<\/a> is organizing two upcoming virtual conferences:<\/p>\n

    Write the Docs Portland 2022<\/a> will take place on May 22-24, 2022. As of the publication date of this post, tickets are still available and the full schedule is up on the conference site<\/a>. As some of you may recall, I had such a great experience at the virtual WtD Portland 2021 conference that I devoted an entire Docs Roundup post to recapping the event<\/a>.<\/p>\n

    Write the Docs Prague 2022<\/a> will take place on September 11-13, 2022; the CFP has yet to be posted.<\/p>\n

    2022 ATTW Conference<\/h1>\n

    The Association of Teachers of Technical Writing<\/a> (ATTW) will hold its annual conference virtually from June 20-30, 2022):<\/p>\n

    Our 2022 conference will span 10 days and include approximately 34 Taking Action workshops, a keynote speaker, an opening session, and an awards session. Check out the full CFP<\/a> for topic ideas and our call to action.<\/p><\/blockquote>\n

    The full schedule is not yet available, but this year’s theme is “Taking Action: Reimagining Just Futures in Technical Communication.”\u00a0Dr. Safiya Noble<\/a>, author of Algorithms of Oppression: How Search Engines Reinforce Racism<\/a> (2018), will be keynoting.<\/p>\n

    \n

    @jsanofranchini<\/a>, @kristen4moore<\/a>, and I are excited to announce the #ATTW22<\/a> virtual conference keynote speaker, Dr. @SafiyaNoble<\/a>!<\/p>\n

    Save the date for her keynote address:
    Wednesday, June 22 at 2PM EDT via Zoom.<\/p>\n

    Details about conference registration coming soon! Follow @ATTWorg<\/a>. pic.twitter.com\/AVj506uCcq<\/a><\/p>\n

    — Donnie Johnson Sackey \ud83e\udd74 (@donniejsackey) April 15, 2022<\/a><\/p><\/blockquote>\n