About Stash's docs

This page provides some transparency on our docs philosophy and how our docs are put together. As time goes by, our philosophies and tooling may change.

Audience

Stash's technical documentation is primarily meant for engineers. This doesn't mean that non-technical users won't find our docs helpful, it just means our main goal is to help engineers understand and use our products.

Docs values

At Stash, we feel that technical docs should be:

Clearly written
Concise
Well organized
Easy to navigate
Searchable
Scannable
Comprehensive but not exhaustive

Comprehensive but not exhaustive

Stash doesn't document every possible workflow within our products. What this means in practice is that Stash tells you where or how to do something, but we won't always provide steps like this:

Navigate to the Web Shop configuration page.
Click Web Shop name.
Enter the name of your shop in the Name field.
Click Save.

Steps like that are often cumbersome, error prone, and add complexity. What Stash does instead is tell you where to go to make a change and provide a direct link when possible. This approach allows us to focus on higher priority content and makes docs maintenance easier.

Information architecture

Stash's docs are organized by product at the top level. One level deeper, Stash uses the Diataxis framework to organize content. The primary content types are how-tos, explanations, and the API reference.

How-tos are task-based docs. You might also know this content type as goal-based or procedural docs. These docs walk you through multiple steps to achieve an outcome.

Explanations (sometimes known as informational or conceptual content) help you understand something. They aren’t task-based or procedural.

These content types add consistency, and provide you with clear options when searching through Stash's docs. They also make it possible to know a doc's purpose before even opening the page.

Interactive demos

Static screenshots are often used to document GUIs but this is sometimes antithetical. GUIs are interactive and have transitions and animations. Stash uses interactive demos to document these flows as much as possible. You can click on the hotspots to interact with our demos.

Docs tech stack

Stash uses a combination of:

Docs are written in Markdown and stored in GitHub. Most changes follow the standard pull request flow. Stash also uses Vale and Alex for docs linting.

Maintenance

Docs maintenance and keeping docs up to date with product changes are classic challenges. Stash uses a combination of manual and automated approaches to keep docs fresh.

Manual efforts

The team regularly reviews existing docs to make sure they're up to date. Friday is the default day for these reviews but they happen off that cycle as well.

Product changes are communicated internally and docs work is a part of the development process. Existing docs are updated as needed, and new docs are written with consideration for what's already live.

Automation and testing

Docs linting (using Vale and Alex) was mentioned previously, but Stash has a few other things in place. GitHub actions run once a day to test for broken links and spelling errors. We're also experimenting with how to us AI for docs maintenance.

Who writes the docs

Writing documentation is always a team effort. At Stash, technical writers and engineers work together to draft, review, and publish documentation. Depending on the project, marketing, legal, and design might be involved as well.

Contribute to Stash's docs

If you have any thoughts, feedback, requests, or suggested changes, please let us know. You have a few options for contacting us:

Send us an email
Fill out our survey
Create an account with ReadMe and click Suggest Edits on the page you want to suggest a change for
Use the rating widget at the bottom of every page

Thank you in advance for helping us improve the docs! Your feedback is valued and critical for ensuring our docs meet your needs.