-
Notifications
You must be signed in to change notification settings - Fork 512
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #2167 from writethedocs/newsletter-july-2024
Add July 2024 newsletter
- Loading branch information
Showing
2 changed files
with
139 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,136 @@ | ||
| :og:image: https://www.writethedocs.org/_static/logo-opengraph.png | ||
|
|
||
| .. post:: July 08, 2024 | ||
| :tags: newsletter | ||
|
|
||
| ##################################### | ||
| Write the Docs Newsletter – July 2024 | ||
| ##################################### | ||
|
|
||
| Cheers, documentarians! This week has seen a cooling off of temperatures after a heat wave across Europe. Joni Mitchell sang that you don't know what you got till it's gone, and it seems the same is true for things you don't want. I hope you are all able to avoid any unwelcome extremes in your lives, whatever forms they may take. | ||
|
|
||
| In conference news, our Atlantic conference is coming up in September, so `get a ticket </conf/atlantic/2024/tickets/>`__ while you still can. Write the Docs Australia has `announced its call for proposals along with ticket sales </conf/australia/2024/news/announcing-cfp-tickets/>`__, so start getting your ideas in now. And if you're looking farther into the future, the Portland conference has `official dates </conf/portland/2025/news/welcome/>`__, May 4--6, 2025, so mark the time in your calendar. | ||
|
|
||
| We'll be taking our traditional newsletter break for August, but we have plenty to tide you over until then. Read about why networking can be good (even if it's just being nice), how analytics can help you take action on your docs, what technical skills you might want to focus on learning, and how to update legacy docs while keeping up with new changes. | ||
|
|
||
| -------------------------- | ||
| The benefits of networking | ||
| -------------------------- | ||
|
|
||
| In the simplest terms, networking is building relationships with others. As documentarians, we may focus on networking for professional reasons, but building effective social networks may also be professionally valuable. The benefits of any networking may not manifest right away, but contacts can prove valuable in the far-off (and possibly not-so-far-off) future. So if any of the following benefits seem important to you, realize that effective networking starts now… not in the future when you already need it. | ||
|
|
||
| These days, with documentarians getting laid off, a major reason for developing a professional network is to find your next job. It's possible to get a job without personal referrals, but many people get hired because they do have a personal connection to someone. A contact may be someone who knows someone who can recommend you. Having personal, trusted referrals can be particularly valuable when competing with hundreds of unfamiliar qualified applicants. | ||
|
|
||
| A recent Slack thread had several anecdotes related to using network connections when job hunting. One person’s connection was from 40 years ago; another’s was from 20 years ago. Others mentioned getting hired permanently after working as contractors or getting referrals because of contracting elsewhere. | ||
|
|
||
| Other networking benefits include professional development (exposure outside your current domain or mentoring within it), finding trusted people to hire yourself, getting effective information (and, possibly, content reviews) from subject matter experts, and developing a community to lean on when needed (not just job hunting — perhaps help with 'imposter syndrome' or safe venting to someone external). | ||
|
|
||
| Realize that helping others is one way to build your network. If you help others out when they need it, they’re more likely to help you when you ask — whether for job hunting or other professional support. | ||
|
|
||
| ------------------------------- | ||
| How to think about docs metrics | ||
| ------------------------------- | ||
|
|
||
| Documentarians in the `#analytics channel <https://writethedocs.slack.com/archives/C5WF43X6G>`__ discussed whether you can effectively improve documentation using docs metrics alone. Most agreed that working from an analytics-generated list of pages and focusing on the worst-performing pages each month is not the best plan. A better approach is to audit the docs' content and combine the findings with your own expertise about the product and content along with metrics such as page views, user sentiment, time on page, and scroll depth. | ||
|
|
||
| To properly interpret metrics, you need to know the content. For example, low time-on-page could mean that the search serves the wrong page... or that the answer to the most common question is in the first sentence. Metrics also can't tell you whether a problem is due to navigation or content. | ||
|
|
||
| You can get actionable information for improving documentation without analytics or metrics. Talking to internal docs users, such as the support team, is a quick way to get information about fixes that may immediately improve quality. You might also consider having subject matter experts review, test, and make suggestions for individual pages. | ||
|
|
||
| Information from user surveys and feedback mechanisms is helpful, with the caveats that these tools take time to create and implement, may have low response rates, and usually don't allow you to clarify user comments. You can also collect user feedback in collaboration with those in customer-facing roles such as sales and support if you develop follow-up questions for them to ask when customers volunteer feedback about the docs. Examples include: | ||
|
|
||
| * Is the documentation incorrect? Difficult to understand? Missing? | ||
| * Did you have trouble finding what you needed? | ||
| * How is the documentation unhelpful? Does it fail to address your questions? Is it irrelevant? | ||
|
|
||
| Documentation benefit maps can be helpful frameworks for thinking about docs quality. A documentation benefit map shows the links between activities, outputs, outcomes, and benefits. For example, if "creating and publishing articles" is listed as an activity, the output might be more articles, with the outcome of decreased onboarding and training costs and the benefit of increased product revenue. | ||
|
|
||
| For more about docs quality and metrics, listen to the MLOps Podcast episode `Just When We Started to Solve Software Docs, AI Blew Everything Up <https://podcasts.apple.com/gb/podcast/just-when-we-started-to-solve-software-docs-ai-blew/id1505372978?i=1000656918860>`__ or read `Beyond Accuracy: What Documentation Quality Means to Readers <https://www.researchgate.net/publication/331088095_Beyond_Accuracy_What_Documentation_Quality_Means_to_Readers>`__ by Yoel Strimling. | ||
|
|
||
| ----------------------------------- | ||
| Technical skills for documentarians | ||
| ----------------------------------- | ||
|
|
||
| A recent Slack discussion explored which area is most worth learning for documentarians: | ||
|
|
||
| - Programming or scripting languages such as Python and Bash | ||
| - Infrastructure or operations tools such as Docker and Kubernetes | ||
|
|
||
| Some urged first learning how to work with command-line interfaces, Docker, or even Kubernetes. Operational examples included understanding the basics of file systems, networking, certificates, and SSHing into a virtual machine. Many agreed on the importance of knowing how to work with cloud computing infrastructure, but also that Python programming skills are useful for documenting APIs. | ||
|
|
||
| ++++++++++++++++++++++++++++ | ||
| Choosing what to learn first | ||
| ++++++++++++++++++++++++++++ | ||
|
|
||
| Operational tooling often requires a documentarian to learn scripting anyway. For instance, modifying a CI/CD content pipeline requires scripts in your pipeline, for tasks such as configuring Docker containers. | ||
|
|
||
| Also, the area to learn first depends on the focus of your current role and the specific product that requires documentation. For instance, roles that work with developer portals and SDKs require programming skills. Alternatively, in some roles, subject matter experts deliver draft content to clean and publish, leaving less need to learn such skills. | ||
|
|
||
| +++++++++++++++++++++++++++++++++++++ | ||
| Implications of knowledge limitations | ||
| +++++++++++++++++++++++++++++++++++++ | ||
|
|
||
| Documentarians may struggle to document tools or features they can’t use. However, this limitation is necessary in certain scenarios: | ||
|
|
||
| - The learning curve for the undocumented tool or feature is too steep to meet the writing deadline. | ||
| - They don't have access to the systems they're writing about. | ||
|
|
||
| In general, quality suffers when documentarians can't use the tools or features they write about. In many companies, documentarians also play a role within quality assurance and when they can't use the product the development team misses out on useful feedback. | ||
|
|
||
| ----------------------------------- | ||
| Updating the old along with the new | ||
| ----------------------------------- | ||
|
|
||
| In a recent discussion on how to deal with a large amount of inherited content, documentarians emphasized the need to distinguish essential documentation from excessive, unnecessary content. The consensus was clear: focus on what truly adds value. For outdated content, one suggestion was to hand over useful legacy documents to users while prioritizing new content that delivers value. | ||
|
|
||
| One great piece of advice was to say "no" to unfeasible requests early on. This helps avoid last-minute rejections and ultimately benefits the company more. Simplifying documentation was another key step, together with streamlining or eliminating outdated text to free up time for future updates. | ||
|
|
||
| Regularly reviewing content keeps it relevant and valuable, preventing the buildup of redundant information. You can even use an "update-as-you-go" strategy, focusing on new features and addressing old documentation only when an update affects it. This means prioritizing new content and selectively updating older guides based on metrics, necessity, or available time. | ||
|
|
||
| Overall, the conversation highlighted the importance of efficient, focused documentation management. By regularly reviewing and updating content, companies can ensure their documentation stays current, is aligned with business objectives, and supports better operational efficiency and outcomes. | ||
|
|
||
| ---------------- | ||
| From our sponsor | ||
| ---------------- | ||
|
|
||
|
|
||
| This month’s newsletter is sponsored by `GitBook <https://www.gitbook.com/?utm_campaign=product-docs&utm_medium=email&utm_source=write_the_docs&utm_content=newsletter>`_: | ||
|
|
||
| ------ | ||
|
|
||
| .. image:: /_static/img/sponsors/gitbook.png | ||
| :align: center | ||
| :width: 75% | ||
| :target: https://www.gitbook.com/?utm_campaign=product-docs&utm_medium=email&utm_source=write_the_docs&utm_content=newsletter | ||
| :alt: GitBook logo | ||
|
|
||
| +++++++++++++++++++++++++++++++++ | ||
| Product docs your users will love | ||
| +++++++++++++++++++++++++++++++++ | ||
|
|
||
| GitBook has everything you need to create beautiful docs for your users — so you don’t have to build your own editing tools, CMS, website, and more. You can just focus on writing great content. | ||
|
|
||
| GitBook’s branch-based Git workflow encourages your whole team to collaborate by creating a branch, requesting a review, and merging when ready. It’s a flow your developers already know and love — and they can even edit your docs in their code editor using Git Sync. | ||
|
|
||
| That’s all backed up by AI that lets your users find what they need fast, publishing settings that put you in control of who can access your docs, and internal documentation for your own team. | ||
|
|
||
| Sign up today and `get started for free <https://www.gitbook.com/?utm_campaign=product-docs&utm_medium=email&utm_source=write_the_docs&utm_content=newsletter>`__! | ||
|
|
||
| ------ | ||
|
|
||
| *Interested in sponsoring the newsletter? Take a look at our* `sponsorship prospectus </sponsorship/newsletter/>`__. | ||
|
|
||
| ---------------- | ||
| Events coming up | ||
| ---------------- | ||
|
|
||
| - 11 Jul, 19:00 CEST (Barcelona, Spain): `Social meetup: Networking & discuss technical writing trends and predictions <https://www.meetup.com/write-the-docs-barcelona/events/301874031/>`__ | ||
| - 11 Jul, 18:30 PDT (Portland, USA): `Portland Documentarian Virtual Social <https://www.meetup.com/write-the-docs-pdx/events/301715687/>`__ | ||
| - 12 Jul, 08:30 EDT (New England and Florida, USA): `Social Hour for Documentarians <https://www.meetup.com/boston-write-the-docs/events/301790302/>`__ | ||
| - 16 Jul, 19:00 EDT (Pittsburgh, USA): `Crafting Clarity: Enhancing AI with Conversation Design <https://www.meetup.com/write-the-docs-pittsburgh/events/301878672/>`__ | ||
| - 17 Jul, 19:00 EDT (Toronto, Canada): `Write the Docs Toronto <https://www.meetup.com/write-the-docs-toronto/events/301908849/>`__ | ||
| - 25 Jul, 18:00 BST (London, United Kingdom): `Write the Docs Summer Social! ☀️ <https://www.meetup.com/write-the-docs-london/events/301483890/>`__ | ||
| - 26 Jul, 08:30 EDT (New England and Florida, USA): `Documentarian Meetup <https://www.meetup.com/boston-write-the-docs/events/301790303/>`__ | ||
| - 31 Jul, 17:15 AEST (Australia): `Brisbane (Onsite): Hello, AI. Please review my content. <https://www.meetup.com/write-the-docs-australia/events/301133834/>`__ | ||
| - 21 Aug, 19:00 EDT (Toronto, Canada): `Write the Docs Toronto <https://www.meetup.com/write-the-docs-toronto/events/mnpqgsygclbcc/>`__ | ||
| - 6 Sep, 08:30 EDT (New England and Florida, USA): `Documentarian Meetup <https://www.meetup.com/boston-write-the-docs/events/kxjjmtygcmbjb/>`__ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters