Software development is changing, and so are documentation needs. For the longest time, humans (Software Engineers, Product Managers etc.) have been the sole users of documentation. They use documentation as guides to learn about new tools and how to use them. This means Technical writers have had to ensure that documentation stay updated, relevant and accurate. They’d frequently sync with product and engineering teams to learn about new features, audit docs for broken links, and fix or replace stale content. This process hasn’t changed a bit, however the pace and standard for keeping documentation relevant just got higher.
Humans are no longer the only users of documentation, we have the new users known as AI Agents. Software developers use these Agents to ship faster. The agents connect to documentation, read through them and use the information they need to build and ship products, at a faster rate. Features that used to take a month can now be built in days, yet documentation still have to stay updated, to ensure relevance and accuracy.
To be honest, managing this manually would be a daunting task. A Technical Writer or team of Technical Writers who try to keep up with this pace could get exhausted and the docs would be prone to error. To be efficient, they’ll need the right tools to automates relevant processes while still staying in the loop. Thally is that tool.
This article introduces Thally - the Documentation tool for the AI era, explains how it works, and guides you through how to build your first Thally documentation.
What is Thally?
Thally is the product knowledge layer for software teams. I’d like to call it the knowledge layer for the AI era. It is designed for product teams who care to serve both humans and agents. And most importantly, it ensures that the product content on your documentation, websites and other knowledge layers are monitored and updated where and when necessary, so writers can focus on what matters.
Thally provide tools for building, deploying, tracking, updating and observing your product knowledge bases.
How Thally Works
Connects to product repository: Thally requests for and connects to the repository where your product, documentation, website, support or knowledge systems live, so it can monitor for changes.
Tracks and updates changes: Once there’s an update in the repo, Thally tracks the change, evaluates it and creates a pull request for review.
Content update: Once the pull request is reviewed and approved, Thally updates the change in the relevant content page.
Analytics: Thally keeps an eye on the published content, observing and tracing impacts across all relevant content layers.
Building with Thally
Thally allows you to either build agent-ready documentation from scratch or import from other documentation platforms. You can import from platforms like Gitbook, Mintlify, Docusaurus, Vitepress, Nextra, and Starlight.
Building a new documentation
You can build with Thally in 2 major ways:
Thally Cloud: With Thally cloud, you can build, deploy, track, update, observe and manage your documentation or knowledge base through your Thally platform.
Thally offers a free .thally.app domain for this feature. You can also connect your custom domain when you want.
Thally CLI: With Thally CLI, you can serve and host your documentation platform locally, then deploy it wherever you want.
However, Thally recommends that you use the Thally Cloud option for seamless management of your product knowledge bases.
Building your first Thally documentation
In this section, you’ll be learning how to build your first documentation on the Thally platform.
You’ll follow along with the steps in this guide, to get the result on the ui below:
For the purpose of this guide, you’ll recreate the Mastra Documentation with me. Mastra is a Typescript framework for building AI agents.
Disclaimer: This documentation and its content is independent of the Mastra brand. It is designed soly for learning purpose. To learn about Mastra, please look up the official Mastra documentation for relevant information.
Stage 1 - Setting up
To follow along with this guide, you’ll need to create an account on Thally. A free account will do just fine for now.
Once your account has been set up, you should see a workspace like the one below. You can create and manage your documentation site on this workspace.
To create your new documentation site, click on the yellowish-green create a site button on the top-right corner of the dashboard.
Next, you’ll be asked to give your site a name, enter a suitable name and a one-line description of your project site in the inputs provided. Then click on the Continue button below.
Where does your docs live?. In this section, you can either create a Github repo for your docs, paste a docs link or use an existing repo. For this example, we’ll be creating a new Github repo for the docs.
Next you’ll have to check if Thally is already connected to your github account, if not, you’ll be prompted to connect. Click on the Check Github button to verify.
If your Github doesn’t have Thally installed already?, now you’ll have to install. Click on the Install app button provided.
Now Thally can access your github repositories, select which repository you would want your docs to live in or create a new repo.
In my case, I selected a repo I created for the docs already. Once you’ve selected, you can press Continue.
Now your docs site is ready to be published. Review your settings, then click on Publish site.
Once published, you’ll find a summary data on your dashboard. Click on the live link to see your site preview.
You’ll see a live preview like the image below, with a few files and placeholder data to get you started.
Now you have to update the docs with your own content.
Stage 2 - Edit content
Once your docs is published, the content files are pushed to your github repo. Visit the repository you connected (you can find the link to your repo on the component where your live-preview link is). Open and clone the repo to your local machine.
After the cloning is completed, open the folder in your code editor of choice.
To preview the page locally, ensure you are in the project directory, then run npm install to install all dependencies.
Next, run npm run dev to preview.
Now you’re ready to start editing your docs content. You’re mostly going to edit the files in src/content for page content, docs.json for information architecture and data/site.ts for brand customization.
You’ll work on the content file first because you’ll need them to create the information architecture (navigation and sidebar) of the documentation.
You can edit the existing files or create a new .MDX file if you need more content. For this guide we’ll be working with the existing files.
Edit File Content.
Every page in the MDX file has 2 sections, the upper-part for the frontmatter and the lower part for MD and MDX content.
The frontmatter contains meta-data about the page like the page title, description etc. and is useful in describing the page content and it’s seo visibility.
You can learn more about how frontmatter in Thally works.
The MD and MDX section is where you write your Markdown files or import MDX (React-like) components.
Open introduction.md and change the title of the introduction page to “What is Mastra?”. And it’s description to “Discover what Mastra is, who it is for and how to start building with Mastra”
For the content on the section, please copy the file content from the Github repo for this project.
The file content would be plain text, except where other components are necessary. Visit components to see all Thally components available to you and how to use them.
Every other headings in the page must be from heading 2 (denoted with ##) and below. The page title is automatically an heading1.
Once you’re done editing the file, save and ensure also to change the file name to align with its title.
Edit all other files too.
Information Architecture
Once your content files are ready. Navigate to docs.json to edit the navigation for the docs.
In the "tabs" array objects, values for "tab" properties are what you see on the navigation bar, while "groups" and "pages" are the sidebars. Check out the file on github and edit to have the exact navbar on the final ui.
Finishing up
Once you you’re done with the edits, ensure to commit your changes. Then run the prompts below before pushing to github.
npx --yes @thallylabs/cli@latest check
npm run build
Once your files have been pushed to github, Thally automatically tracks and loads the changes to your site. Refresh your live preview link to see your updated site.
Viola! You have built your first Thally documentation site.
Conclusion
This article explained why technical writers need efficient tools like Thally to keep up with the pace of how software products are being shipped in the AI era. It further introduced Thally and how it works, then guided you on a journey to building a Mastra documentation with Thally.
If you would like to learn more about how Thally works, please visit the Thally website and official documentation for relevant information.
