writeexperience.co A well-organized and accessible documentation site is a cornerstone of user experience. It’s not just about presenting information but also about navigation and ease of access. Among the essential elements, the header stands out as a prime spot to include crucial links and menus for swift navigation. If you’re using the ReadTheDocs theme and seeking … Read more
A well-structured documentation homepage serves as the gateway to your product documentation. So, it must be easy to navigate and enable discoverability of your content. In this blog post, I provide a template that you can customize to create a documentation page. This template relies heavily on the elements from the sphinx-design extension, specifically cards, … Read more
In this guide, I will walk you through the process of integrating Typesense with the Read the docs theme for your documentation website. This integration allows you to add a powerful search feature to your documentation, making it easier for users to find the information they need. Summary: Before we begin, let’s outline the infrastructure … Read more
Documentation for our products (static site) is stored in S3. Recently, due to a new product launch, the AWS account that hosted the S3 bucket was rendered inaccessible. We had to move all the documentation to a new S3 bucket in a different AWS account. The problem we faced is how do we redirect the … Read more
Customizing Default Changelist Description in Perforce To improve the traceability of commits to perforce, we were looking to provide a changelist description template to the team. We use Perforce as a repository running on a Windows platform. Research from the internet suggested that we would have to use P4 triggers. However, our IT team had … Read more
Problem: Formatting is not retained after updating cross-reference You insert a cross-reference to a section. And, you apply a character style to display the link in blue. However, when you update the cross-reference, the character styling is lost. For example, if you have applied a style to display the link in blue, the formatting is … Read more
Traditionally in our product group, we have been using unstructured FrameMaker as the main authoring tool for our product documentation. In late 2017, we received a requirement that customer requires our documentation source in DITA format with the PDFs too. This requirement posed a challenge. We did not have any experience working with DITA earlier, … Read more
In this post, I explain how you can write a GitHub action that will generate HTML from Restructured Text (reST) and upload the HTML files to an S3 bucket. This workflow ensures that when you merge any changes to your reST source, the HTML is automatically built and posted to your hosting provider. Introduction Creating … Read more