From 5db3baaeb5080593c664ea0f6a6fbe4531f9eb29 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Wed, 4 Oct 2023 14:39:00 +0200 Subject: [PATCH 1/8] Update newsletter template for capitalization --- docs/organizer-guide/newsletter/newsletter-process.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/organizer-guide/newsletter/newsletter-process.rst b/docs/organizer-guide/newsletter/newsletter-process.rst index bdef84ccc1..db5e0eb116 100644 --- a/docs/organizer-guide/newsletter/newsletter-process.rst +++ b/docs/organizer-guide/newsletter/newsletter-process.rst @@ -91,7 +91,7 @@ Once all the story drafts have come in, it's time to assemble, based on the outl CONTENT. ---------------- - From our sponsor + From Our Sponsor ---------------- This month’s newsletter is sponsored by SPONSOR: @@ -120,7 +120,7 @@ Once all the story drafts have come in, it's time to assemble, based on the outl *Interested in sponsoring the newsletter? Take a look at our* `sponsorship prospectus `__. ------------------ - Featured job posts + Featured Job Posts ------------------ - `TITLE `__, COMPANY (LOCATION) @@ -128,7 +128,7 @@ Once all the story drafts have come in, it's time to assemble, based on the outl *To apply for these jobs and more, visit the* `Write the Docs job board `_. ---------------- - Events coming up + Events Coming Up ---------------- - 00 MONTH, TIME ZONE (location) - `TITLE `__ From ef9260b686ba98e068877195912a290df757c1aa Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Fri, 6 Oct 2023 11:34:13 +0200 Subject: [PATCH 2/8] Add October 2023 newsletter --- ...etto_Square__For_Non_White_Backgrounds.png | Bin 0 -> 17130 bytes docs/blog/newsletter-october-2023.rst | 130 ++++++++++++++++++ docs/topics.rst | 3 + 3 files changed, 133 insertions(+) create mode 100644 docs/_static/img/sponsors/Heretto_Square__For_Non_White_Backgrounds.png create mode 100644 docs/blog/newsletter-october-2023.rst diff --git a/docs/_static/img/sponsors/Heretto_Square__For_Non_White_Backgrounds.png b/docs/_static/img/sponsors/Heretto_Square__For_Non_White_Backgrounds.png new file mode 100644 index 0000000000000000000000000000000000000000..5b9f1331ed42d2019f428ca9ca714a9619ab3704 GIT binary patch literal 17130 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 Hu(`__ is open and accepting submissions! This is the survey's fifth year and, in addition to our regular salary and job-related questions, we're exploring our community's thoughts on "back to the office" mandates, feelings about job security in a volatile market, and attitudes towards pay transparency. + +So whether you're an employee, contractor, freelancer, or currently unemployed, `head on over `_ and help us make this year's survey the most useful yet. + +In conference news, `tickets for the in-person Australia conference `__ are still open. If you'd like to apply for an `opportunity grant `__, you have until 15 October. + +The newsletter this month covers how to include links within your docs, whether you can show some of your personality in your docs, how to handle docs in the same repository as product source code, and how much (or little) to capitalize feature names. Hope you enjoy! + +-------------- +Hyperlink Text +-------------- + +How to deal with links is a recurring question for documentarians. To answer it, some people suggested guidelines from the `W3C `__, `Microsoft `__, and `Google `__. + +The general consensus was to include text that's relevant — not just ‘click here’. Suggestions included using the linked page’s title, turning the title into relevant text, and creating descriptive text based on the context. Non-writers (such as developers) may prefer using the title for simplicity. More experienced documentarians may want to craft the text. + +There are several issues involved: + +- If there are inadequate guidelines for cross-referencing content, new or updated guidelines may be needed. +- The page title may be too long or unhelpful. If so, either edit the title or summarize the content in a few words. +- Some documentation systems focus on short, succinct topics. This may require many links to cross-reference content adequately. + +A related issue concerns *where* to put the links: throughout the content or at the end of the content in a separate list? The main arguments against putting links at the end: the link may have lost its context or the reader may never scroll that far. In either case, it’s important to use relevant text. Having the link within the content may disrupt the reader by triggering cognitive overload and making them wonder: "Should I click or not? Should I click as I come to the link or wait until I finish reading?" + +If you put links within the content, `one reference suggested `__ always putting the link at the end of the sentence to minimize distraction. Accessibility was an additional concern, but exact solutions were unclear because interpretation depends upon the screen reader. + +-------------------------------- +Personality in Technical Writing +-------------------------------- + +There are still different views among documentarians on the issue of the importance of personality, customization, and tone in technical writing. People recently shared their thoughts on the topic, giving different points of view on whether such things belong in technical documents. + +Some people said that strict accuracy was the most important in technical writing, while others said that there was room for creativity and humor as long as precision wasn’t compromised. In particular, they said that adding a bit of personality can make such writing more interesting, especially if the readers can handle it. + +Context also came up as an essential factor, with people agreeing that different kinds of technical material need different levels of formality. For example, troubleshooting guides should always be very clear, while onboarding tutorials might benefit from a more friendly tone. + +Also, many people stressed the importance of knowing the audience and suggested that the amount of personalization should match what they want and expect. Some even pushed for tech writing that changes the language by using broader terms and more open methods to improve users' experience. + +Most people agreed that the audience’s needs should always come first. Individuality, personalization, and tone can improve technical writing in some situations, but isn't appropriate everywhere. Finding the best mix between readability, accuracy, and interest is important for making technical documentation that users can relate to and use to reach their goals. + +----------------------------------- +Docs *with* Code Or Just *as* Code? +----------------------------------- + +Someone who switched jobs recently asked in `#docs-as-code `__ about the benefits and drawbacks of keeping docs in the same repository as app code. They moved from having docs in a separate repository to docs in the same repository as the product source code and were feeling frustrated. + +Some of the perceived drawbacks to keeping docs with app code included changes feeling slower and less flexible, requiring PRs for everything, even small typos. Each change also required reviews from developers and lots of linting when app code wasn't touched. Also, collaboration seemed more difficult than in tools like Google Docs and Notion. In short, it felt like there were roadblocks everywhere. + +People noted some potential benefits, including increased accountability for changes with PRs. Some also felt safer knowing any mistakes weren't theirs alone and that the CI checks and reviews helped keep entire pages from breaking. Someone also noted that with docs in the same repository as code, it was easier to enforce docs changes when code is updated, including potentially automating some changes. + +People had some suggestions to help overcome some roadblocks. Opening PRs early in the process lets reviewers check out changes locally to see the effects. Someone also suggested using the principle of pair programming in pair reviews for easier collaboration: run the docs locally and walk through the changes on a video call. It was also suggested to keep PRs small and therefore manageable, but batch really small things like typos together if each PR takes too long. And encourage improvements to the CI to catch typos earlier and also only run when needed (not linting untouched code). + +Either setup can work and each works for some situations. As someone pointed out, if you're going to use docs-as-code, it's best to optimize for the code tools and processes available to you. + +-------------------------- +Capitalizing Feature Names +-------------------------- + +How much is too much when it comes to capitalizing the names of features in the docs? The limit may be lower than you think! This month, most documentarians recommended using capitalization only sparingly in your documentation. + +Unnecessary capitalization is distracting for readers. It looks odd in English, especially when the words aren't proper nouns. Capitalizing generic terms like "dashboard" or "alert" makes it more difficult for readers to understand whether you're talking about the general meaning of the word or a specialized concept. + +In addition, many writing systems do not used mixed case, and capitalization norms vary among languages, so excessive capitalization can make it more difficult to translate your documentation. It's also difficult to remove over-capitalization programmatically, particularly when certain words should retain capitalization in a specific context. + +If you want to establish a precedent, it can be helpful to take a look at other companies' docs. Also, capitalization and naming is often covered in style guides -- check out these examples: + +* `Shopify Polaris `_ +* `Splunk `_ +* `IBM Carbon Design System `_ + +For a designer's take on the subject, read `Fighting Feature Names `_ by Scott Kubie. + +---------------- +From Our Sponsor +---------------- + +This month’s newsletter is sponsored by Heretto: + +.. raw:: html + +
+ + + + + + + +
+

+ At Heretto, we’re thrilled to unveil a game-changing feature for tech writers and developers alike: Interactive API Docs. +

+

+ API Docs empowers companies to consolidate their product and API documentation into a single-source repository for a seamless user experience. +

+

+ Unify your docs on one branded site, test APIs in seconds, and drive API adoptions with search-ready documentation. +

+

+ Want to learn more? Meet with our team to see API Docs in action. +

+ 		+ + Heretto + +
+
+ +*Interested in sponsoring the newsletter? Take a look at our* `sponsorship prospectus `__. + +---------------- +Events Coming Up +---------------- + +- 6 Oct, 08:30 EDT (New England and Florida, USA): `Focused conversation: Document types and templates `__ +- 7 Oct, 19:30 EAT (Nairobi, Kenya): `Documentation Localization in Open Source `__ +- 12 Oct, 18:30 EDT (Pittsburgh, USA): `UX writing for the rest of us `__ +- 18 Oct, 08:00 PDT (Seattle, USA): `Write the Docs Seattle: Casual Caffeine Hour `__ +- 19 Oct, 17:30 CDT (Austin, USA): `Write the Docs ATX Happy Hour Meetup: October 19th `__ +- 20 Oct, 08:30 EDT (New England and Florida, USA): `Focused Conversation for Documentarians `__ +- 3 Nov, 08:30 EDT (New England and Florida, USA): `Focused Conversation for Documentarians `__ diff --git a/docs/topics.rst b/docs/topics.rst index cf4ef332b3..87445c4492 100644 --- a/docs/topics.rst +++ b/docs/topics.rst @@ -32,6 +32,7 @@ Grammar Naming and terminology ~~~~~~~~~~~~~~~~~~~~~~ +- |:newspaper:| `Capitalizing Feature Names `__ - |:newspaper:| `Common words and how to identify them `__ - |:movie_camera:| `Even Naming This Talk Is Hard `__ - |:movie_camera:| `Whatchamacallit: Controlled Vocabularies for Technical Writers `__ @@ -42,6 +43,7 @@ Specific writing questions One word vs another, using abbreviations, etc. +- |:newspaper:| `Hyperlink Text `__ - |:newspaper:| `Numbering Section Headings `__ - |:newspaper:| `Gerunds in headings `__ - |:newspaper:| `When to use acronyms `__ @@ -498,6 +500,7 @@ Doc tools Docs-as-code ~~~~~~~~~~~~ +- |:newspaper:| `Docs with Code Or Just as Code? `__ - |:movie_camera:| `One AWS team’s move to docs as code: what worked, what didn’t, what’s next `__ - |:newspaper:| `To git or not to git docs as code `__ - |:newspaper:| `Pros and cons of the docs-as-code approach `__ From 506cf8d0ebd5514b011911ac4955ad1e00918ba4 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Fri, 6 Oct 2023 11:38:32 +0200 Subject: [PATCH 3/8] Update publish date --- docs/blog/newsletter-october-2023.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/newsletter-october-2023.rst b/docs/blog/newsletter-october-2023.rst index 27a8a29bb1..7c60f45aa5 100644 --- a/docs/blog/newsletter-october-2023.rst +++ b/docs/blog/newsletter-october-2023.rst @@ -1,4 +1,4 @@ -.. post:: October 02, 2023 +.. post:: October 06, 2023 :tags: newsletter ######################################### From d98648f884d07e021e6cbd6a86e28ba729025dd3 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Fri, 6 Oct 2023 11:45:47 +0200 Subject: [PATCH 4/8] Fix links --- docs/topics.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/topics.rst b/docs/topics.rst index 87445c4492..f498b19834 100644 --- a/docs/topics.rst +++ b/docs/topics.rst @@ -32,7 +32,7 @@ Grammar Naming and terminology ~~~~~~~~~~~~~~~~~~~~~~ -- |:newspaper:| `Capitalizing Feature Names `__ +- |:newspaper:| `Capitalizing Feature Names `__ - |:newspaper:| `Common words and how to identify them `__ - |:movie_camera:| `Even Naming This Talk Is Hard `__ - |:movie_camera:| `Whatchamacallit: Controlled Vocabularies for Technical Writers `__ @@ -43,7 +43,7 @@ Specific writing questions One word vs another, using abbreviations, etc. -- |:newspaper:| `Hyperlink Text `__ +- |:newspaper:| `Hyperlink Text `__ - |:newspaper:| `Numbering Section Headings `__ - |:newspaper:| `Gerunds in headings `__ - |:newspaper:| `When to use acronyms `__ @@ -500,7 +500,7 @@ Doc tools Docs-as-code ~~~~~~~~~~~~ -- |:newspaper:| `Docs with Code Or Just as Code? `__ +- |:newspaper:| `Docs with Code Or Just as Code? `__ - |:movie_camera:| `One AWS team’s move to docs as code: what worked, what didn’t, what’s next `__ - |:newspaper:| `To git or not to git docs as code `__ - |:newspaper:| `Pros and cons of the docs-as-code approach `__ From 3115d1346e4d382abe02312669104074f1f1271d Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Fri, 6 Oct 2023 10:47:48 +0000 Subject: [PATCH 5/8] Apply suggestions from review Co-authored-by: Sam --- docs/blog/newsletter-october-2023.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/blog/newsletter-october-2023.rst b/docs/blog/newsletter-october-2023.rst index 7c60f45aa5..1dee8bcd25 100644 --- a/docs/blog/newsletter-october-2023.rst +++ b/docs/blog/newsletter-october-2023.rst @@ -37,7 +37,7 @@ If you put links within the content, `one reference suggested Date: Fri, 6 Oct 2023 12:54:55 +0000 Subject: [PATCH 6/8] Apply suggestions from review Co-authored-by: Hillary Fraley <19190208+hillaryfraley@users.noreply.github.com> --- docs/blog/newsletter-october-2023.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/blog/newsletter-october-2023.rst b/docs/blog/newsletter-october-2023.rst index 1dee8bcd25..ad78833841 100644 --- a/docs/blog/newsletter-october-2023.rst +++ b/docs/blog/newsletter-october-2023.rst @@ -39,7 +39,7 @@ Personality in Technical Writing There are still different views among documentarians on the issue of the importance of personality, customization, and tone in technical writing. -Some people said that strict accuracy was the most important in technical writing, while others said that there was room for creativity and humor as long as precision wasn’t compromised. In particular, they said that adding a bit of personality can make such writing more interesting, especially if the readers can handle it. +Some people said that strict accuracy was the most important consideration in technical writing, while others said that there was room for creativity and humor as long as precision wasn’t compromised. In particular, they said that adding a bit of personality can make such writing more interesting, especially if the readers can handle it. Context also came up as an essential factor, with people agreeing that different kinds of technical material need different levels of formality. For example, troubleshooting guides should always be very clear, while onboarding tutorials might benefit from a more friendly tone. @@ -57,7 +57,7 @@ Some of the perceived drawbacks to keeping docs with app code included changes f People noted some potential benefits, including increased accountability for changes with PRs. Some also felt safer knowing any mistakes weren't theirs alone and that the CI checks and reviews helped keep entire pages from breaking. Someone also noted that with docs in the same repository as code, it was easier to enforce docs changes when code is updated, including potentially automating some changes. -People had some suggestions to help overcome some roadblocks. Opening PRs early in the process lets reviewers check out changes locally to see the effects. Someone also suggested using the principle of pair programming in pair reviews for easier collaboration: run the docs locally and walk through the changes on a video call. Another idea was keeping PRs small and therefore manageable, but batching really small things like typos together if each PR takes too long. And encouraging improvements to the CI to catch typos earlier and also only runing when needed (not linting untouched code). +People had some suggestions to help overcome some roadblocks. Opening PRs early in the process lets reviewers check out changes locally to see the effects. Someone also suggested using the principle of pair programming in pair reviews for easier collaboration: run the docs locally and walk through the changes on a video call. Another idea was keeping PRs small and therefore manageable, but batching really small things like typos together if each PR takes too long. And encouraging improvements to the CI to catch typos earlier and also only running when needed (not linting untouched code). Either setup can work and each works for some situations. As someone pointed out, if you're going to use docs-as-code, it's best to optimize for the code tools and processes available to you. From adb6263c94a802df9663695aab054e0e4627ed01 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Fri, 6 Oct 2023 15:18:07 +0000 Subject: [PATCH 7/8] Add note about Australia conference speakers --- docs/blog/newsletter-october-2023.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/newsletter-october-2023.rst b/docs/blog/newsletter-october-2023.rst index ad78833841..0ee0bec60c 100644 --- a/docs/blog/newsletter-october-2023.rst +++ b/docs/blog/newsletter-october-2023.rst @@ -11,7 +11,7 @@ The Write the Docs `Documentarian Salary Survey for 2023 `_ and help us make this year's survey the most useful yet. -In conference news, `tickets for the in-person Australia conference `__ are still open. If you'd like to apply for an `opportunity grant `__, you have until 15 October. +In conference news, the in-person Australia conference has just `announced its speakers . Check out the amazing talks you have to look forward to and then `grab a ticket `__. If you'd like to apply for an `opportunity grant `__, you have until 15 October. The newsletter this month covers how to include links within your docs, whether you can show some of your personality in your docs, how to handle docs in the same repository as product source code, and how much (or little) to capitalize feature names. Hope you enjoy! From 2b743b845cf06163dd3603a18df8b8510855f27c Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Fri, 6 Oct 2023 15:18:43 +0000 Subject: [PATCH 8/8] Fix link --- docs/blog/newsletter-october-2023.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/newsletter-october-2023.rst b/docs/blog/newsletter-october-2023.rst index 0ee0bec60c..be4bc660c5 100644 --- a/docs/blog/newsletter-october-2023.rst +++ b/docs/blog/newsletter-october-2023.rst @@ -11,7 +11,7 @@ The Write the Docs `Documentarian Salary Survey for 2023 `_ and help us make this year's survey the most useful yet. -In conference news, the in-person Australia conference has just `announced its speakers . Check out the amazing talks you have to look forward to and then `grab a ticket `__. If you'd like to apply for an `opportunity grant `__, you have until 15 October. +In conference news, the in-person Australia conference has just `announced its speakers `__. Check out the amazing talks you have to look forward to and then `grab a ticket `__. If you'd like to apply for an `opportunity grant `__, you have until 15 October. The newsletter this month covers how to include links within your docs, whether you can show some of your personality in your docs, how to handle docs in the same repository as product source code, and how much (or little) to capitalize feature names. Hope you enjoy!