How to coordinate a docs release with a product release
You also need to define Git best practices for your team about how to manage those, such as:
Whether to use release branches, or merge pull requests frequently but publishing infrequently.
Whether to use Git rebase or Git merge to maintain Git history in a given branch.
Whether and how to use feature branches and pull requests.
Whether to squash merge pull requests to main.
Even if you manage to define best practices that your team is committed to following, there isn’t a way to force your documentation contributors to adhere to all of these best practices. Due to the lack of enforcement of these best practices, you can easily end up in a situation where writers follow slightly different practices based on what their tools make easy to do."
The #writethedocs community has been discussing #docsascode a lot the past few days, and it pushed me to finally finish and publish a post I've been noodling on for months... docs as code is a broken promise 🙈
#SoftwareDocumentation#DocsAsTests#DocsAsCode#APIDocumentation#TechnicalWriting#SoftwareTesting#SoftwareDevelopment: "I initially developed and implemented Docs as Tests at Skyflow, a startup that moves fast and releases features and updates even faster than I’d experienced before. I searched for tools to help me manage the pace of changes: there were style linters, API testers, and engineering-focused testing tools, but there wasn’t anything to easily help me validate the product descriptions or procedures in my docs. So I built my own, and Doc Detective was born. Doc Detective is a toolkit that parses docs and runs tests (like stepping through procedures) directly against UIs and APIs. It’s designed so non-engineers can use it individually, but teams can also collaborate. When I set it up to test my docs, it caught issues that I had no idea of. It was a game-changer.
But Doc Detective is just a tool (a good one, I like to think!), and no tool solves every problem. I wanted to find a way to apply my learnings to the broader docs community, and I came up with Docs as Tests—a strategy that can be implemented with whichever tools you choose to validate your docs. I’m excited to share my learnings with you and to learn from you as well."
#TechnicalWriting#DocsAsCode#SoftwareDocumentation#SoftwareDevelopment#Git: "Following the docs-as-code approach means continuously testing and deploying (publishing) updated content. So, if you’re documenting a big new feature or reworking a section of your docs, you want to avoid the interim results going into production while letting the other members of your team continuously publish their updates.
Authoring tools provide different workarounds for this – you can mark a topic as a draft, exclude it from your table of contents map, or even prepare new content as a draft in Google Docs and only incorporate it into your sources after it’s been finalized.
If we use developer terminology here, this way you can perform unit testing of your docs, but you will then need to perform integration testing when you incorporate new or updated content into your source base. Using Git branches helps to avoid isolating the piece you’re working on from the rest of your docs and review and test it as an integral part of your online help portal."
For at least 10 years I've had a career goal of speaking at a conference.
I can't believe it's taken me this long to achieve this goal, but I've finally done it. 😊
It was an improvised 5-minute lightning talk about doing #DocsAsCode from scratch at a small company.
The audience seemed to respond well, some people talked about it with me afterwards, and I achieved my main goal of telling lots of clever knowledgeable people about the challenges I'm trying to address. Yay!