Home »

Write the Docs Newsletter – April 2025¶

Hi, documentarians. As I write this, the sun is once again shining through my window and the weather is heating up. The perennials on my balcony have started to open up after winter. Hope is in the air. I hope you can find similar inspiration somewhere around you and that the forecasted dropping temperatures over the weekend don’t send things spiraling backwards.

Write the Docs Portland has just announced the full schedule. So check it out, get excited for it all to start next month, and grab your tickets if you haven’t yet.

This month’s newsletter has articles on organizing content, learning docs-as-code, growing your career in a one-person team, and SEO for docs. Enjoy!

How to organize content in your documents¶

Should your online documentation have long pages with related content or separate pages of focused content (Every page is page one)? As a documentarian, how you organize content can depend on the content, your audience, the content’s delivery, and the content strategy.

If you decide to have long, comprehensive pages, you may want to include a “mini-table-of-contents” (mini-TOC) on each page or implement a distinct heading system. If you have short, focused topics, a comprehensive TOC or navigational structure helps readers locate other topics of interest. (Even if your customers tend to search for content, seeing a well-organized TOC helps readers understand how content fits into the overall documentation.)

Some content may be more suited to long, comprehensive pages (or modularity) rather than short topics. As part of your content strategy, consider what type of content you need to deliver for your audience. For example, reference topics, such as API docs, may fit better on a single page. It’s generally accepted that people retain smaller “chunks” of information better, but if there is a strong correlation, then putting the chucks on one page may make sense.

One person suggested researching the Jobs-to-be-Done framework (for product development), which focuses on what readers want to do rather than product features. Learning how your audience plans to use the product may provide information about how they would want to use the content.

Some people prefer long, comprehensive pages; others prefer short, concise topics. Whether they read on a mobile device, laptop, or desktop computer makes a difference, too. You may have to do an audience survey or A/B testing to determine what your target audience prefers. From that information, you can decide how to organize content. Some documentation systems have a toggle for readers to view content as single or multiple pages.

Several people cautioned about being too fixed with one approach. A well-considered mix of the two may be best for your readers.

See more Write the Docs resources about information-architecture.

Learn docs-as-code¶

If you want to learn the docs-as-code approach to documentation, but not necessarily in the context of API docs, your best bet is to combine a variety of materials to make your own “training.” Write the Docs resources are a great starting point: find books and talks on the Docs as Code resource page and previous newsletter items in the Docs-as-code content archive. And don’t forget that you can ask questions in the #docs-as-code channel in WTD Slack!

Version control is an important element of docs-as-code, and learning Git will help you understand docs-as-code processes and collaboration methods. It’s also a good idea to learn a tool that uses Git, like GitHub or GitLab. Peter Greunbaum’s Git and GitHub for Writers course on Udemy covers both and comes highly recommended.

Docs-as-code typically involves writing in Markdown syntax and publishing with tools called static site generators (SSGs). Several documentarians recommended Manny Silva’s course Demystifying Docs-as-Code because it demonstrates how to initiate a docs-as-code project using the popular SSG Docusaurus.

See more Write the Docs resources about docs-as-code.

Leveling up as a solo documentarian¶

Working alone as a documentarian and feeling stuck in your current role? You’re not alone. Many solo documentarians find themselves in workplaces that don’t prioritize documentation, leaving them with limited opportunities to expand their skills. If you’re in this position, don’t wait for growth opportunities – create them! Here’s some ideas on how from #career-advice:

Seek out problems and solve them
- Identify gaps in existing documentation or areas that need more clarity.
- Talk to customer support or engineers to uncover frequent pain points.
- Turn these insights into FAQs, internal knowledge bases, or process docs.
Build your own portfolio
- Even if your leadership doesn’t prioritize documentation, write it anyway.
- Create deep-dive guides, whitepapers, or best practices—whether or not someone requested them.
- Treat it as a way to showcase your skills for future roles.
Go beyond writing
- Develop standards and style guides to improve documentation quality.
- Mentor non-writers on best practices to create a stronger writing culture.
- Consider branching into related roles like product management or UX writing.
Expand your learning outside work
- Take online courses on API documentation, structured authoring, or AI in tech communications.
- Contribute to open-source projects to gain real-world experience.
- Get involved in professional communities such as Write the Docs.

If you love your workplace but crave more growth, lean into the skills you can develop. But if stagnation is holding you back, don’t be afraid to explore new opportunities. Your career is yours to shape!

See more Write the Docs resources about career growth.

SEO for docs: How much and how?¶

A question was recently raised about whether technical documentation could benefit from search-engine optimization (SEO) or whether to push back against people requesting it.

In general, respondents agreed that it was worth doing SEO work within reason. In fact, one person noted that keeping docs within general standards of clarity, structure, and accessibility is already a good start for many SEO practices. Another noted this may be enough for small collections of docs, but larger ones have more of a need for SEO. It’s important to make sure your content is findable and useful to your customers.

Pretty much everyone agreed that it wasn’t necessary to aim for SEO at the cost of usability. Don’t stuff keywords into your docs just to try to climb the rankings, only when it makes sense to help explain the topic.

There were a few practices people mentioned as useful for docs, such as linking practices, conventions for URL slugs, and canonical metadata. The last is especially important if you have versioned or translated content. You want to make sure you point search engine crawlers to the latest version of a given doc and don’t get punished for “duplicated” content.

See more Write the Docs resources about search.

Write the Docs resources¶

Write the Docs offers lots of valuable resources related to documentation. See all of the Write the Docs learning resources. To discuss any of these ideas or others related to documentation, join the conversation in the Write the Docs Slack community in one of the many channels.