From 4187ab0effbe52e7c82db9966da2dc64eeb91c6e Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Fri, 13 Sep 2024 16:09:29 -0600 Subject: [PATCH] fix: italics where it APPEARS to have been intended... ...and ended up "_like this_" inside an .RST file which merely puts underscores on either side of the terms which APPEAR to have been intended to be standard "emphasized" words, but appears to be a possible export-translation error from some software, which put the syntax for Markdown _italics_ rather than reStructuredText *italics*. I saw one of these while I was reading and decided to LOOK for such occurrences throughout the website .RST files and found these 5 occurrences. An issue was not created for this. --- docs/blog/newsletter-december-2021.rst | 2 +- docs/blog/newsletter-december-2022.rst | 2 +- docs/blog/newsletter-february-2021.rst | 2 +- docs/blog/newsletter-november-2021.rst | 2 +- docs/blog/newsletter-october-2017.rst | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/blog/newsletter-december-2021.rst b/docs/blog/newsletter-december-2021.rst index 3d6d284c1a..75ef1474cd 100644 --- a/docs/blog/newsletter-december-2021.rst +++ b/docs/blog/newsletter-december-2021.rst @@ -8,7 +8,7 @@ Write the Docs Newsletter – December 2021 Hey everyone, -The year is drawing to a close - thank goodness, if you ask me - and we’re back with the very last edition of the newsletter for 2021. It’s been a _complicated_ year but not without its highlights - our second year of virtual conferences plus the just-wrapped-up Australia super-meetup. Thanks for being such a great community through it all 💖 +The year is drawing to a close - thank goodness, if you ask me - and we’re back with the very last edition of the newsletter for 2021. It’s been a *complicated* year but not without its highlights - our second year of virtual conferences plus the just-wrapped-up Australia super-meetup. Thanks for being such a great community through it all 💖 One last call for folks who haven’t yet filled out the `Salary Survey `__. We’d love it if you would consider contributing the details of your compensation. It’s all anonymous and the anonymised results are released for free, so everyone in the community can benefit. `Fill it out here `__. diff --git a/docs/blog/newsletter-december-2022.rst b/docs/blog/newsletter-december-2022.rst index 507ec412f7..efa3a831f1 100644 --- a/docs/blog/newsletter-december-2022.rst +++ b/docs/blog/newsletter-december-2022.rst @@ -33,7 +33,7 @@ When working with other documentarians, it’s useful to be able to criticise co Trying to give better feedback is hard work, but it’s also worth the effort. If you have colleagues whose writing could be better, they’re not likely to improve without thoughtful criticism. That's where some useful tips, shared by our community this month, come in. -First up, if you're faced with a bad piece of writing: Know that giving constructive criticism to help someone else improve it _will_ take longer than just rewriting it yourself. You have to accept that this is an investment of time today, which will only pay off in the long run. +First up, if you're faced with a bad piece of writing: Know that giving constructive criticism to help someone else improve it *will* take longer than just rewriting it yourself. You have to accept that this is an investment of time today, which will only pay off in the long run. In the same vein, the idea is to help another writer grow. So consider what exact area they need to work on and then focus on that. It may feel less scary to focus on corrections to spelling and grammar, but those comments won’t help your colleague improve if their real issue is wordiness or a lack of clarity. diff --git a/docs/blog/newsletter-february-2021.rst b/docs/blog/newsletter-february-2021.rst index 9249e4a06b..2074d969a2 100644 --- a/docs/blog/newsletter-february-2021.rst +++ b/docs/blog/newsletter-february-2021.rst @@ -16,7 +16,7 @@ So what's been happening on Slack? Getting the balance right with screenshots ------------------------------------------ -In December, documentarians had a lively discussion about how many screenshots to include in docs. As you might imagine, perspectives ranged from "absolutely no screenshots ever" to "as many screenshots as possible," but the most common opinion was "it depends" (surprise!). Most said they try to help both users who like a visual walkthrough _and_ users who prefer to follow text instructions. One writer approached the problem by presenting text explanations as the default, with an optional collapsible version that includes screenshots. +In December, documentarians had a lively discussion about how many screenshots to include in docs. As you might imagine, perspectives ranged from "absolutely no screenshots ever" to "as many screenshots as possible," but the most common opinion was "it depends" (surprise!). Most said they try to help both users who like a visual walkthrough *and* users who prefer to follow text instructions. One writer approached the problem by presenting text explanations as the default, with an optional collapsible version that includes screenshots. Fewer screenshots means less maintenance work. If the product changes, the screenshots must change too, to remain helpful and prevent confusion. Lots of screenshots plus frequent product changes can cost a lot of time: keeping the docs in sync with the product can become unmanageable. diff --git a/docs/blog/newsletter-november-2021.rst b/docs/blog/newsletter-november-2021.rst index 892d88f146..7d7cef02f9 100644 --- a/docs/blog/newsletter-november-2021.rst +++ b/docs/blog/newsletter-november-2021.rst @@ -40,7 +40,7 @@ Documentation gets respect (or at least attention) Two recent reports highlight the increased attention documentation seems to be getting in the worlds of software development. -The `2021 State of DevOps report from Google Cloud `__ includes data showing the effects of docs quality on devops team performance, and describes practices to improve the quality of your documentation. The report is based on seven years of research and data from more than 32,000 professionals worldwide, focusing on "capabilities and practices that drive software delivery, operation, and organizational performance." So the focus is not on docs -- but the report includes good documentation as one of six findings characteristic of the 26% of teams studied who fall into the highest performing category. This is _internal_ documentation, and its quality has a statistically significant impact on how secure, reliable, and effective a team's devops practices are. Quality documentation efforts should include critical use cases for products and services, guidelines for updating and editing existing documentation, clearly defined ownership and responsibility for documentation, inclusion of docs as part of the software development process, and recognition of docs work during performance reviews and promotions. +The `2021 State of DevOps report from Google Cloud `__ includes data showing the effects of docs quality on devops team performance, and describes practices to improve the quality of your documentation. The report is based on seven years of research and data from more than 32,000 professionals worldwide, focusing on "capabilities and practices that drive software delivery, operation, and organizational performance." So the focus is not on docs -- but the report includes good documentation as one of six findings characteristic of the 26% of teams studied who fall into the highest performing category. This is *internal* documentation, and its quality has a statistically significant impact on how secure, reliable, and effective a team's devops practices are. Quality documentation efforts should include critical use cases for products and services, guidelines for updating and editing existing documentation, clearly defined ownership and responsibility for documentation, inclusion of docs as part of the software development process, and recognition of docs work during performance reviews and promotions. The `State of Software Quality API 2021 report `__ from SmartBear similarly points to "accurate and detailed documentation" as a key aspect of the overall success of an API, second only to "ease of use" for API consumers. Disappointingly few survey respondents rated their API docs as "Very Good" -- but only 16% of teams include technical writers for their API docs. On the other hand, more than half the respondents contribute to API docs in some way, and 60-70% of respondents work for companies that include a formal API documentation process -- but only about half of those companies consider documentation a priority. Respondents cited a range of obstacles to providing quality documentation, but they all fell into the larger category of insufficient resources -- time, tools, personnel, budget, and more. On another front, our documentarians who so diligently work with OpenAPI definitions will be happy to read that OpenAPI usage continues high, but GraphQL and AsyncAPI continue to grow in popularity. diff --git a/docs/blog/newsletter-october-2017.rst b/docs/blog/newsletter-october-2017.rst index f88d0677df..1a441543bf 100644 --- a/docs/blog/newsletter-october-2017.rst +++ b/docs/blog/newsletter-october-2017.rst @@ -52,7 +52,7 @@ If you're a lone writer, you've probably been in the unenviable position of not ************************************************ Defining developer relations/evangelism/advocacy ************************************************ -This month, someone asked a question which many of us have wondered about, at one point or another: "What does a developer advocate or evangelist actually do?" (You may have even wondered this _as_ a developer advocate/evangelist...) +This month, someone asked a question which many of us have wondered about, at one point or another: "What does a developer advocate or evangelist actually do?" (You may have even wondered this *as* a developer advocate/evangelist...) The ensuing conversation made it clear that whether you call it developer relations (DevRel), developer evangelism, or developer advocacy, it can mean a lot of different things. But some common themes emerged: