90TI Docs

Summary

90TI Docs is a comprehensive knowledge base and documentation platform I developed as a Software Developer at 90TI, a Brazilian software company specializing in construction management solutions. Built with Next.js, the platform serves as a centralized hub for all public software documentation, making complex technical information easily accessible to both users and prospective clients.

My role

I was responsible for the entire development of the 90TI Docs platform, from initial concept to production deployment. Additionally, I mentored the QA team on best practices for authoring and maintaining documentation articles.

Motivation

The project emerged from a critical business need at 90TI. The company's software documentation was scattered across multiple platforms, making it difficult for users to find answers to their questions. This resulted in increased support tickets and user frustration. As the company's product portfolio expanded, the need for a centralized, searchable knowledge base became paramount.

Technical Planning

I began by analyzing the existing documentation structure and feedback from both team members and clients to understand pain points. The initial design focused on:

• Information architecture: Hierarchical organization that mirrors how users think about the products and their features.
• UX: The documentation must allow fast navigation and quick access to information, even with a large number of articles.
• Maintainability: The documentation must be easy to maintain, and also migrate to another platform if needed in the future.

UI

The UI design was crafted to be clean, modern, and user-friendly, with a focus on readability and ease of navigation. Key features include:

• Responsive design: Ensures a seamless experience across devices, from desktops to mobile phones.
• Dark and ligt mode: A toggle for dark and light mode, catering to user preferences and improving accessibility.
• Semantic HTML: The documentation is structured using semantic HTML elements, enhancing accessibility and SEO.

Git as CMS

During team discussions, we recognized the importance of enabling both developers and less-technical team members to contribute to the documentation. At the same time, we needed a reliable way to manage version control and implement a review workflow.

To address these needs, instead of building some kind of CMS or using an existing one, we adopted the "Git as CMS" approach. By storing our documentation in a Git repository, we benefit from powerful versioning capabilities and seamless collaboration across the team.

Every documentation article is stored as a MDX file, allowing us to write content in Markdown while also embedding React components for interactive elements. This approach not only simplifies the writing process but also enhances the user experience by enabling custom documentation components.

Custom components for special articles

Leveraging the power of MDX, we enhanced the user experience by embedding custom React components directly into the documentation. One example is the “Brand Guidelines" article, which features custom components to display brand colors and all brand and product logos.

Search engine

To ensure users can quickly find the information they need, I implemented a simple but effective search engine. This allows for fast, full-text search across all documentation articles.

In the future, this can be replaced with a more advanced solution, such as Algolia or Meilisearch, to further enhance search capabilities and performance.

SSG and CI/CD

The documentation platform is built using Next.js, which allows for Static Site Generation (SSG). This means that all documentation articles are pre-rendered at build time, ensuring fast load times and optimal performance.

The CI/CD pipeline is set up to automatically build and deploy the documentation whenever changes are pushed to the main branch of the Git repository. This ensures that the latest documentation is always available to users without manual intervention.

PWA for mobile users

One of the requirements for the project was to ensure that mobile and tablet users could access the documentation easily. To achieve this, the platform was made available as a Progressive Web App (PWA). This allows users to install the documentation on their devices, providing a native app-like experience with offline access and fast loading times.

Main takeaways

The 90TI Docs project was a significant achievement that addressed a critical business need. By centralizing documentation and making it easily accessible, we reduced support tickets and improved user satisfaction. The use of Git as a CMS allowed for efficient collaboration and version control, while the custom components and search engine enhanced the overall user experience.