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:

1. Navigate to the Webshop configuration page.
2. Click Webshop name.
3. Enter the name of your shop in the Name field.
4. 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

The docs IA has changed over time. It’s roughly organized like this now:

• Get started: Content that helps users figure out where to start, and how to complete any required steps for using Stash.
• Learn: Content that focuses on educating users about Stash’s products.
• Build: Task-based content that tells users how to do something with Stash.
• SDKs and tooling: Content that explains how to use SDKs and Stash tooling.
• Migration guides: Content that explains how to move from an existing provider to Stash.

We don’t have formal doc types, but we try to keep docs focused on specific goals. This generally means either educating the user on a specific topic, or guiding them through how to do something.

Interactive demos

Static screenshots are often used to document GUIs but this isn’t optimal. 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:

• Nextra
• MDX
• GitHub
• Swagger
• Vale
• Alex
• Lychee
• Arcade

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 as well. 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.