From 6925fd4c826378fa26662f823c80597687331f25 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Tue, 5 Nov 2024 22:22:40 +0100 Subject: [PATCH 1/7] Add November 2024 newsletter --- docs/blog/newsletter-november-2024.rst | 73 ++++++++++++++++++++++++++ docs/topics.rst | 3 ++ 2 files changed, 76 insertions(+) create mode 100644 docs/blog/newsletter-november-2024.rst diff --git a/docs/blog/newsletter-november-2024.rst b/docs/blog/newsletter-november-2024.rst new file mode 100644 index 000000000..4cc517d2b --- /dev/null +++ b/docs/blog/newsletter-november-2024.rst @@ -0,0 +1,73 @@ +:og:image: https://www.writethedocs.org/_static/logo-opengraph.png + +.. post:: November 05, 2024 + :tags: newsletter + +######################################### +Write the Docs Newsletter – November 2024 +######################################### + +Greetings, documentarians. In these bustling days of news and planning, I hope you are able to find moments of calm for yourselves to appreciate what is going well. + +If you have enough calm and want some inspiration, good news: The Write the Docs Australia conference is coming soon! Tickets close on Saturday 16 November, so `get your tickets `__ while you still can. + +The `WTD Salary Survey for 2024 `__ is now open! New this year: you can fill the survey out as both an employee and contractor, if you've worked as both during the past year; answers can be edited before the final submission; and for privacy, salary/rate fields are masked by default. Head on over and share your insights – each contribution helps build a clearer picture of what fair, equitable, and transparent compensation looks like in our industry. Full-time or part-time, permanent or contract, working or currently between jobs – we want your input! + +And in the newsletter this month, we have insights into whether to use emoji in docs, whether you need to know a tool before applying to work with it, and dealing with assets with docs-as-code. Enjoy! + +---------------------------------------------- +Emoji in documentation: :yes-please: or :yuk:? +---------------------------------------------- + +Emoji seem to find their way into documentation more and more often these days... but is that a good or a bad idea? Well, like everything else, it depends! A sprinkling of emoji can work well in some cases and cause more problems than they're worth in others. + +Emoji can help achieve an inviting and approachable tone for certain types of documentation, such as quick start guides aimed at developers. Because emoji can make content feel less dense and more engaging, they may be especially appropriate for contexts such as presales documentation, where a whiff of marketing-speak is acceptable. Emoji may also be used to differentiate a newcomer's product from existing enterprise offerings. And emoji in tables can make the information easier for readers to scan, although icons used as inline images can achieve the same thing. + +On the other hand, emoji can cause accessibility issues because they aren't necessarily interpretable by assistive technology (read `Do emoji and accessibility work together? `_ by Di Mace for details). The meanings of emoji may be interpreted differently across cultures, so you risk sending a different message than you intended when you use emoji. Emoji can be distracting or even inconsiderate to a confused reader. Documentarians may also spend a lot of time trying to use emoji to affect a chatty tone instead of writing clearly and end up with content that doesn't actually explain anything. It's best to carefully consider your audience and approach emoji use with caution. + +---------------------------------------- +Are tool experience requirements a myth? +---------------------------------------- + +Job postings often request experience with specific tools. Recently, in the `#career-advice channel `__, a job seeker asked how important this is for experienced documentarians. + +The general consensus was that lack of experience with a specific tool shouldn’t prevent someone from applying for a position. Documentation managers want people who can understand and write clearly and concisely about technical concepts and related procedures. Possibly, experience with a specific audience (or domain) may be important. In fact, many mentioned that throughout their careers their various employers (or even the same company) used different tools. + +A hiring manager focused on how quickly the person can get up to speed with the team. If you’re a quick learner, have experience with other relevant tools, and are self-motivated enough to self-study (if necessary), lack of specific tooling experience isn’t a problem. If you don’t have experience with a specific tool, use an interview to relate how you learned other tools. + +Several concerns included: + +* **If your resume doesn’t mention ANY tool specified in a job posting, the application may get rejected automatically.** This is particularly true if you’re going through a recruiter. It may be worthwhile to gain at least a novice-level exposure to include on your resume. (Don’t lie about your experience.) Many tools are either free or have free trials available. +* **There may be some basic tool-related knowledge that’s expected with certain types of documentation.** If you’re transitioning to another domain, consider getting at least minimal exposure to relevant knowledge (such as Markdown, Git, or HTML). +* **Some "tools" are actually concepts.** You may want to research what certain items (such as DITA, distributed systems, or version control) involve so you can discuss them. + +Some companies do expect to train new hires. If nothing else, new hires need to learn the way the team uses a particular tool. If hired, be prepared to learn from others even if you have experience with their tools. + +---------------------------------------------------- +Dealing with images and other assets in docs-as-code +---------------------------------------------------- + +A couple of recent questions regarding `#docs-as-code `__ touched on how to handle binary files such as images in a docs-as-code setup, which is primarily built to track text files. One concern was the size of the binary files, which can make a Git repository balloon up to gigabytes in size. Another issue was whether to store images next to the file they're used in or in a separate directory only for images. + +Unsurprisingly, the answers on what to do varied based on what was required. For example, if you only need simply diagrams, you can create them using a diagrams-as-code tool such as `Mermaid `__ or `PlantUML `__ and track them like any other text file. If you need large files, such as computer-aided design (CAD) files, you might want to look into `Git Large File Storage `__ to point to the files in a separate location. + +If you land somewhere in between, your organizational options may depend on your build tool. Some require images to be stored in specific places to take advantage of their workflows. If your tool is more flexible, consider whether you're like to reuse the images across docs. If not, consider storing the images in a subdirectory with the doc. For example, `src/get-started/intro.md` could have images like `src/get-started/img/flow.png`. This option keeps things organized by topic. + +If you will reuse images, consider storing all images within a single directory, which you can separate into subdirectories by topic or product. When images are separate from the docs, see if you can use a helper tool like a `path autocomplete extension for your IDE `__ to make writing the locations easier. + +------------------ +Featured job posts +------------------ + +`Technical Documentation Lead `__, Nutrient (Remote) + +---------------- +Events coming up +---------------- + +- 12 Nov, 19:00 MST (Calgary, Canada): `How a Technical Writer can Drive a Successful QMS Implementation `__ +- 15 Nov, 08:30 EST (East Coast Quorum, USA): `Social Hour for Documentarians `__ +- 19 Nov, 18:45 EST (Washington, USA): `2024 WTD DC End of Year Happy Hour `__ +- 20 Nov, 18:00 CET (Berlin, Germany): `WTD Berlin @ JetBrains - Svetlana Novikova - Beyond static docs `__ +- 20 Nov, 18:00 CET (Stockholm, Sweden): `Let's talk about tools and processes, AI or not `__ +- 21 Nov, 17:00 PST (Portland, USA): `AI for Documentarians: Write the Docs PDX + PSU Annual Supermeetup `__ diff --git a/docs/topics.rst b/docs/topics.rst index a0ae5b9c0..25615c1ec 100644 --- a/docs/topics.rst +++ b/docs/topics.rst @@ -43,6 +43,7 @@ Specific writing questions One word vs another, using abbreviations, etc. +- |:newspaper:| `Emoji in documentation: :yes-please: or :yuk:? `__ - |:newspaper:| `Hyperlink Text `__ - |:newspaper:| `Numbering Section Headings `__ - |:newspaper:| `Gerunds in headings `__ @@ -298,6 +299,7 @@ Hiring Getting hired ~~~~~~~~~~~~~ +- |:newspaper:| `Are tool experience requirements a myth? `__ - |:newspaper:| `Handling employment gaps `__ - |:newspaper:| `Setting Up for Success as a Neurodivergent Person `__ - |:newspaper:| `Extreme take-home tests `__ @@ -516,6 +518,7 @@ Doc tools Docs-as-code ~~~~~~~~~~~~ +- |:newspaper:| `Dealing with images and other assets in docs-as-code `__ - |:newspaper:| `Is Docs-as-Code Worth It? `__ - |:newspaper:| `Drafting Docs with Code Changes `__ - |:newspaper:| `Docs with Code Or Just as Code? `__ From 4bb00cbca42e98dcbb328e34a5f491e83d16aae0 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Wed, 6 Nov 2024 08:50:14 +0100 Subject: [PATCH 2/7] Prose improvements after review --- docs/blog/newsletter-november-2024.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/blog/newsletter-november-2024.rst b/docs/blog/newsletter-november-2024.rst index 4cc517d2b..acce85202 100644 --- a/docs/blog/newsletter-november-2024.rst +++ b/docs/blog/newsletter-november-2024.rst @@ -11,7 +11,7 @@ Greetings, documentarians. In these bustling days of news and planning, I hope y If you have enough calm and want some inspiration, good news: The Write the Docs Australia conference is coming soon! Tickets close on Saturday 16 November, so `get your tickets `__ while you still can. -The `WTD Salary Survey for 2024 `__ is now open! New this year: you can fill the survey out as both an employee and contractor, if you've worked as both during the past year; answers can be edited before the final submission; and for privacy, salary/rate fields are masked by default. Head on over and share your insights – each contribution helps build a clearer picture of what fair, equitable, and transparent compensation looks like in our industry. Full-time or part-time, permanent or contract, working or currently between jobs – we want your input! +The `WTD Salary Survey for 2024 `__ is now open! New this year: you can fill the survey out as both an employee and contractor if you've worked as both during the past year; answers can be edited before the final submission; and for privacy, salary/rate fields are masked by default. Head on over and share your insights – each contribution helps build a clearer picture of what fair, equitable, and transparent compensation looks like in our industry. Full-time or part-time, permanent or contract, working or currently between jobs – we want your input! And in the newsletter this month, we have insights into whether to use emoji in docs, whether you need to know a tool before applying to work with it, and dealing with assets with docs-as-code. Enjoy! @@ -21,9 +21,9 @@ Emoji in documentation: :yes-please: or :yuk:? Emoji seem to find their way into documentation more and more often these days... but is that a good or a bad idea? Well, like everything else, it depends! A sprinkling of emoji can work well in some cases and cause more problems than they're worth in others. -Emoji can help achieve an inviting and approachable tone for certain types of documentation, such as quick start guides aimed at developers. Because emoji can make content feel less dense and more engaging, they may be especially appropriate for contexts such as presales documentation, where a whiff of marketing-speak is acceptable. Emoji may also be used to differentiate a newcomer's product from existing enterprise offerings. And emoji in tables can make the information easier for readers to scan, although icons used as inline images can achieve the same thing. +Emoji can help achieve an inviting and approachable tone for certain types of documentation, such as quick start guides. Because emoji can make content feel less dense and more engaging, they may be especially appropriate for contexts such as presales documentation, where a whiff of marketing-speak is acceptable. Emoji may also be used to differentiate a new product from existing enterprise offerings. And emoji in tables can make the information easier for readers to scan, although icons used as inline images can achieve the same thing. -On the other hand, emoji can cause accessibility issues because they aren't necessarily interpretable by assistive technology (read `Do emoji and accessibility work together? `_ by Di Mace for details). The meanings of emoji may be interpreted differently across cultures, so you risk sending a different message than you intended when you use emoji. Emoji can be distracting or even inconsiderate to a confused reader. Documentarians may also spend a lot of time trying to use emoji to affect a chatty tone instead of writing clearly and end up with content that doesn't actually explain anything. It's best to carefully consider your audience and approach emoji use with caution. +On the other hand, emoji can cause accessibility issues because they aren't necessarily interpretable by assistive technology. (For details, read `Do emoji and accessibility work together? `_ by Di Mace.) The meanings of emoji may be interpreted differently across cultures, so you risk sending a different message than you intended when you use emoji. Emoji can be distracting or even inconsiderate to a confused reader. Documentarians may also spend a lot of time trying to use emoji to affect a chatty tone instead of writing clearly and end up with content that doesn't actually explain anything. It's best to carefully consider your audience and approach emoji use with caution. ---------------------------------------- Are tool experience requirements a myth? @@ -49,9 +49,9 @@ Dealing with images and other assets in docs-as-code A couple of recent questions regarding `#docs-as-code `__ touched on how to handle binary files such as images in a docs-as-code setup, which is primarily built to track text files. One concern was the size of the binary files, which can make a Git repository balloon up to gigabytes in size. Another issue was whether to store images next to the file they're used in or in a separate directory only for images. -Unsurprisingly, the answers on what to do varied based on what was required. For example, if you only need simply diagrams, you can create them using a diagrams-as-code tool such as `Mermaid `__ or `PlantUML `__ and track them like any other text file. If you need large files, such as computer-aided design (CAD) files, you might want to look into `Git Large File Storage `__ to point to the files in a separate location. +Unsurprisingly, the answers on what to do varied based on what was required. For example, if you only need simple diagrams, you can create them using a diagrams-as-code tool such as `Mermaid `__ or `PlantUML `__ and track them like any other text file. If you need large files, such as computer-aided design (CAD) files or videos, you might want to look into `Git Large File Storage `__ to point to the files in a separate location. -If you land somewhere in between, your organizational options may depend on your build tool. Some require images to be stored in specific places to take advantage of their workflows. If your tool is more flexible, consider whether you're like to reuse the images across docs. If not, consider storing the images in a subdirectory with the doc. For example, `src/get-started/intro.md` could have images like `src/get-started/img/flow.png`. This option keeps things organized by topic. +If you land somewhere in between, your organizational options may depend on your build tool. Some require images to be stored in specific places to take advantage of their workflows. If your tool is more flexible, consider whether you're likely to reuse the images across docs. If not, consider storing the images in a subdirectory with the doc. For example, `src/get-started/intro.md` could have images like `src/get-started/img/flow.png`. Doing this keeps files organized by topic. If you will reuse images, consider storing all images within a single directory, which you can separate into subdirectories by topic or product. When images are separate from the docs, see if you can use a helper tool like a `path autocomplete extension for your IDE `__ to make writing the locations easier. From b751e38ec7cb091d1290e1bdfa49ecfd115fac1b Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Wed, 6 Nov 2024 08:50:46 +0100 Subject: [PATCH 3/7] Improve job post Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/blog/newsletter-november-2024.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/blog/newsletter-november-2024.rst b/docs/blog/newsletter-november-2024.rst index acce85202..3aa5e74d4 100644 --- a/docs/blog/newsletter-november-2024.rst +++ b/docs/blog/newsletter-november-2024.rst @@ -59,8 +59,9 @@ If you will reuse images, consider storing all images within a single directory, Featured job posts ------------------ -`Technical Documentation Lead `__, Nutrient (Remote) +`Technical Documentation Lead `__, Nutrient (Remote) +Interested in promoting your open position? See our `job posting sponsorship `__ for more details. ---------------- Events coming up ---------------- From 11e95f63ecc1b431299c0f920e40f6c0922ebac7 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Wed, 6 Nov 2024 09:10:19 +0100 Subject: [PATCH 4/7] Add fourth article and update publish date --- docs/blog/newsletter-november-2024.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/blog/newsletter-november-2024.rst b/docs/blog/newsletter-november-2024.rst index 3aa5e74d4..da06a9b19 100644 --- a/docs/blog/newsletter-november-2024.rst +++ b/docs/blog/newsletter-november-2024.rst @@ -1,6 +1,6 @@ :og:image: https://www.writethedocs.org/_static/logo-opengraph.png -.. post:: November 05, 2024 +.. post:: November 06, 2024 :tags: newsletter ######################################### @@ -13,7 +13,7 @@ If you have enough calm and want some inspiration, good news: The Write the Docs The `WTD Salary Survey for 2024 `__ is now open! New this year: you can fill the survey out as both an employee and contractor if you've worked as both during the past year; answers can be edited before the final submission; and for privacy, salary/rate fields are masked by default. Head on over and share your insights – each contribution helps build a clearer picture of what fair, equitable, and transparent compensation looks like in our industry. Full-time or part-time, permanent or contract, working or currently between jobs – we want your input! -And in the newsletter this month, we have insights into whether to use emoji in docs, whether you need to know a tool before applying to work with it, and dealing with assets with docs-as-code. Enjoy! +And in the newsletter this month, we have insights into whether to use emoji in docs, whether you need to know a tool before applying to work with it, dealing with assets with docs-as-code, and using a template for release notes. Enjoy! ---------------------------------------------- Emoji in documentation: :yes-please: or :yuk:? @@ -55,6 +55,21 @@ If you land somewhere in between, your organizational options may depend on your If you will reuse images, consider storing all images within a single directory, which you can separate into subdirectories by topic or product. When images are separate from the docs, see if you can use a helper tool like a `path autocomplete extension for your IDE `__ to make writing the locations easier. +--------------------------------------------- +Streamline your release notes with a template +--------------------------------------------- + +For members of the Write the Docs community, the topic of release notes often sparks lively discussion. Whether you're a solo technical writer or part of a larger team, establishing a structured approach to release notes can streamline workflows and enhance the value of documentation. One celebrated approach is a template pioneered at Red Hat focused on cause, consequence, fix, and result (CCFR). This format has proven to be a simple yet powerful way to ensure that release notes are clear, actionable, and highly useful to both internal and external audiences. + +Originally created to address customer concerns over unclear documentation, the CCFR template provides a straightforward method for documenting each change: + +1. Cause: Describe what triggers the issue. +2. Consequence: Outline the effects of the issue. +3. Fix: Explain what exactly was done to resolve it. +4. Result: Detail the outcome post-fix. + +This template has helped transform release notes from being a pain point to a respected tool that even supported sales by demonstrating the transparency and reliability of their product updates. Introducing a structure like CCFR in your team, particularly if people who aren't focused on writing are managing release notes, can help standardize the content and increase its effectiveness. It's a strategy worth considering, especially if you want to illustrate the added value a documentarian can bring to release documentation. + ------------------ Featured job posts ------------------ From 2d6425cd2a33aa164fec50c7221c3f6918e8893b Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Wed, 6 Nov 2024 09:23:33 +0100 Subject: [PATCH 5/7] Add missing line --- docs/blog/newsletter-november-2024.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/blog/newsletter-november-2024.rst b/docs/blog/newsletter-november-2024.rst index da06a9b19..8b8d518b8 100644 --- a/docs/blog/newsletter-november-2024.rst +++ b/docs/blog/newsletter-november-2024.rst @@ -77,6 +77,7 @@ Featured job posts `Technical Documentation Lead `__, Nutrient (Remote) Interested in promoting your open position? See our `job posting sponsorship `__ for more details. + ---------------- Events coming up ---------------- From 45ac799a0eecf805b7cbe4a1e8afced9a21ae2c1 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Wed, 6 Nov 2024 18:09:14 +0100 Subject: [PATCH 6/7] Add credit --- docs/blog/newsletter-november-2024.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/newsletter-november-2024.rst b/docs/blog/newsletter-november-2024.rst index 8b8d518b8..25972304a 100644 --- a/docs/blog/newsletter-november-2024.rst +++ b/docs/blog/newsletter-november-2024.rst @@ -59,7 +59,7 @@ If you will reuse images, consider storing all images within a single directory, Streamline your release notes with a template --------------------------------------------- -For members of the Write the Docs community, the topic of release notes often sparks lively discussion. Whether you're a solo technical writer or part of a larger team, establishing a structured approach to release notes can streamline workflows and enhance the value of documentation. One celebrated approach is a template pioneered at Red Hat focused on cause, consequence, fix, and result (CCFR). This format has proven to be a simple yet powerful way to ensure that release notes are clear, actionable, and highly useful to both internal and external audiences. +For members of the Write the Docs community, the topic of release notes often sparks lively discussion. Whether you're a solo technical writer or part of a larger team, establishing a structured approach to release notes can streamline workflows and enhance the value of documentation. One celebrated approach is a template pioneered by Brian Forté at Red Hat focused on cause, consequence, fix, and result (CCFR). This format has proven to be a simple yet powerful way to ensure that release notes are clear, actionable, and highly useful to both internal and external audiences. Originally created to address customer concerns over unclear documentation, the CCFR template provides a straightforward method for documenting each change: From d1d9a5312116d6585186c075a786542c9c1a61f0 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Wed, 6 Nov 2024 18:11:16 +0100 Subject: [PATCH 7/7] Clarity --- docs/blog/newsletter-november-2024.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/newsletter-november-2024.rst b/docs/blog/newsletter-november-2024.rst index 25972304a..012362c87 100644 --- a/docs/blog/newsletter-november-2024.rst +++ b/docs/blog/newsletter-november-2024.rst @@ -68,7 +68,7 @@ Originally created to address customer concerns over unclear documentation, the 3. Fix: Explain what exactly was done to resolve it. 4. Result: Detail the outcome post-fix. -This template has helped transform release notes from being a pain point to a respected tool that even supported sales by demonstrating the transparency and reliability of their product updates. Introducing a structure like CCFR in your team, particularly if people who aren't focused on writing are managing release notes, can help standardize the content and increase its effectiveness. It's a strategy worth considering, especially if you want to illustrate the added value a documentarian can bring to release documentation. +This template helped transform release notes from being a pain point to a respected tool that even supported sales by demonstrating the transparency and reliability of their product updates. Introducing a structure like CCFR in your team, particularly if people who aren't focused on writing are managing release notes, may help standardize the content and increase its effectiveness. It's a strategy worth considering, especially if you want to illustrate the added value a documentarian can bring to release documentation. ------------------ Featured job posts