Intro

Welcome to 2024, where the relentless challenge of documentation persists at 1mg. Despite our best efforts from both frontend and backend developers to diligent product managers, the documentation dilemma remains. We've explored a myriad of solutions—Swagger, Postman, Confluence, PDFs, Word docs, even our custom tools—yet none have quite hit the mark for all our diverse use cases.

Enter OneDoc, our audacious attempt to crack the code on comprehensive documentation. While the aforementioned tools address specific issues admirably, they often fall short when it comes to meeting all our unique needs.

With OneDoc, we're setting out to redefine the way we approach documentation, aiming to bring a unified solution to the table at 1mg!

Understanding the Challenge at Scale

Addressing the documentation challenge may seem straightforward at first glance, but as our requirements multiply at scale, the simplicity transforms into a complex web of intricacies. Our current approach has been use-case specific, utilizing various tools such as:

• Postman: for executing cURL commands

• Swagger: for generating open API based documentation

• Custom UI (Adam): for visualization and search

• Confluence/Google Docs and Word: for product descriptions and general documentation

• PDFs and Emails: for sharing documentation

However, this mix-and-match strategy poses significant risks and challenges:

Consistency and Versioning:

• Different tools introduce distinct formatting and styling, resulting in documentation inconsistencies.

• Version control becomes arduous as information scatters across multiple platforms.

Communication and Collaboration Issues:

• Collaboration becomes challenging as teams navigate documentation scattered across various tools.

• Miscommunication, witnessed in the past, has led to production downtime.

Learning Curve for New Tools:

• The adoption of numerous tools demands a learning curve, potentially impacting team productivity.

Access Control and Security:

• Managing access controls and ensuring data security becomes more challenging in a diverse tool environment.

• Sensitive information might inadvertently be shared through less secure channels.

Documentation Duplication:

• Duplication of information across tools leads to confusion and potential inconsistencies.

• Updates in one tool may not be reflected in others, causing discrepancies.

Searchability and Retrieval Challenges:

• Locating specific information becomes challenging, requiring users to search across multiple platforms.

• The absence of a unified search mechanism may impact efficiency.

Long-Term Maintenance:

• Maintaining documentation across various tools proves time-consuming and poses challenges in the long run.

• Ongoing support and updates become complex with a diverse toolset.

Client Confusion:

• Clients may find it perplexing to navigate through different platforms for various types of documentation.

• Utilizing different tools for sharing information may impact the overall client experience.

As we dive into the intricacies of these challenges, the need for a unified solution becomes evident. Let's explore how OneDoc aims to streamline our documentation processes and overcome these hurdles, paving the way for a more efficient and cohesive approach.

Understanding the Requirements

When we dive into the realm of technical documentation, the initial associations often revolve around API docs and auto-generated code-level documentation. While these elements are crucial and serve as our starting point, the landscape of technical documentation extends far beyond mere readmes and API docs.

To comprehend the scope of the issue, I've categorized technical documentation into five major segments, tailored to the needs of TATA 1mg and companies at our scale:

1. User Documentation:

   • Installation and Setup
   • User Guides
   • FAQs and Troubleshooting

2. Developer Resources:

   • APIs Documentation
   • Functional Documentation
   • SDKs Documentation
   • Widgets Documentations
   • Coding Standards, etc.

3. Communication and Updates:

   • Release Notes
   • News and Updates
   • Announcements

4. System and Product Information:

   • Project Descriptions
   • SLAs Documentation
   • Onboarding Guides

5. Support and Compliance:

   • Troubleshooting and Support
   • Legal and Compliance
   • Accessibility Documentation

Keeping these categories in mind, the following are essential requirements for a documentation tool:

• Standardization in documentation generation from all sources.

• A visualization layer that reads documentation from multiple sources and presents it understandably with doc segregation.

• Responsive UI.

• CMS to manage all documentation.

• Rich text editor for doc editing.

• Review mechanism to control doc publishing.

• Segregation between public docs (shareable with 3rd parties) and private docs (limited to the scope of 1mg).

• RBAC to control editing and uploading permissions.

• Versioning at both doc and service levels.

• Curl execution.

• Code snippets visualization.

• Common search functionality.

• Shareable documentation.

• Development clients.

• Automatic pipelines for doc generation.

Solution - Introducing OneDoc

Having delved into the intricacies of our documentation challenges, we recognized the need for a comprehensive solution that goes beyond niche use cases. Enter OneDoc, our groundbreaking answer to the documentation conundrum.

OneDoc empowers you to effortlessly create, modify, and search through your technical documentation. Its visualization layer simplifies navigation, supporting a dark theme for aesthetic preferences.

Key Features:

• CMS for managing docs.

• Rich text editor.

• Doc and service-level API versioning.

• Curl extraction in any language.

• RBAC.

• Public and private document segregation.

With predefined clients and packages for Python, ROR, NodeJs, Android, and iOS, alongside fully automated document synchronization and build pipelines, onboarding new services becomes a seamless experience.

OneDoc doesn't stop there. It offers a barrage of features to enhance your documentation experience and streamline your processes. Embrace OneDoc, and revolutionize the way you approach and manage your technical documentation.

Architecture

At OneDoc, our approach to building a robust documentation solution involves leveraging the strengths of various open-source tools while crafting our unique solution atop this foundation. The major components contributing to the architecture include:

1. Docusaurus: Docusaurus serves as a foundational element, providing structure and efficiency for the visual element.

2. DeCap: A headless CMS. DeCap plays a crucial role, contributing its capabilities to enhance the functionality and performance of OneDoc by providing a git based CMS for the documentation maintenance.

3. Adam | Swagger | Open API Format: The trio of Adam, Swagger, and adherence to the Open API format ensures a seamless integration of API documentation.

4. Doc Sync Automation: Automation is at the heart of OneDoc's efficiency, all the documentation generated using using decorators is automatically picked up and synced on the OneDoc.

5. Bitbucket for Document Versioning: Bitbucket comes into play to support robust document versioning, all the documentation edits are raised as an automatic PR enabling that can be merged once reviewed.

6. Custom Development: OneDoc incorporates custom development to tailor specific functionalities, ensuring a bespoke solution that aligns precisely with our unique requirements. For the features like:

   • RAML to OPEN API Conversion

   • Public vs Private docs

   • Bulk Documentation uploads

   • RBAC

   • Automation pipelines and much more

7. Custom Deployment: Our custom deployment strategy ensures that OneDoc is deployed optimally, maximising performance and reliability for an exceptional user experience.

By amalgamating these components, OneDoc creates a synergistic architecture that combines the strengths of existing tools with custom-built elements, delivering a documentation solution that stands at the forefront of efficiency, functionality, and user satisfaction.

Code Snippets

Document all of your services using predefined clients and packages for Python, ROR & NodeJs alongside fully automated document synchronization and build pipelines.

Python

Installation

pip install git+ssh://[email protected]/tata1mg/[email protected]

from sanic_ext import validate, openapi
from sanic_ext.extensions.openapi.definitions import Response, Parameter

@test.route("/openapi/description", methods=["PUT"])
@openapi.definition(
    summary="API to generate OpenAPI descriptions using openAI",
    description="The route can be used to generate the descriptions using AI of the OpenAPI Specification files"
    response=[
        Response(
            {
                "application/json": TestAPI.ResponseDataModel,
            },
            description="Success",
            status=201,
        )
    ],
)

Ruby On Rails

Installation

# Gemfile
gem 'rswag-api'

group :development, :test do
  gem 'rspec-rails'
  gem 'rswag-specs'
end

# spec/requests/blogs_spec.rb
require 'swagger_helper'

describe 'Blogs API' do

  path '/blogs' do

    post 'Creates a blog' do
      tags 'Blogs'
      consumes 'application/json'
      parameter name: :blog, in: :body, schema: {
        type: :object,
        properties: {
          title: { type: :string },
          content: { type: :string }
        },
        required: [ 'title', 'content' ]
      }

      response '201', 'blog created' do
        let(:blog) { { title: 'foo', content: 'bar' } }
        run_test!
      end

      response '422', 'invalid request' do
        let(:blog) { { title: 'foo' } }
        run_test!
      end
    end
  end
end

Node JS

Installation

const onedocClientDoc = require('@tata1mg/nodejs-onedoc-client');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0',
    },
  },
  apis: ['./src/routes*.js'], // files containing annotations as above
};

const openapiSpecification = onedocClientDoc(options);

/**
 * @openapi
 * /:
 *   get:
 *     description: Welcome to swagger-jsdoc!
 *     responses:
 *       200:
 *         description: Returns a mysterious string.
 */
app.get('/', (req, res) => {
  res.send('Hello World!');
});

TL;DR:

OneDoc - Revolutionizing Documentation at 1mg Challenges Addressed: Traditional documentation solutions at 1mg lacked the versatility needed for diverse team requirements, leading to the exploration of a more holistic approach.

Problem Insights: The article dissects current challenges, from inconsistent formatting and collaboration issues to potential risks and client confusion arising from the mix-and-match use of tools like Swagger, Postman, and Confluence.

Specific Requirements: Outlining essential features for an ideal documentation tool, the article sets the stage for introducing OneDoc.

OneDoc Unveiled: Positioned as a game-changer, OneDoc standardizes documentation generation, introduces a powerful visualization layer, and offers a responsive UI. Key features include RBAC, public-private document segregation, versioning, and more.

Architecture Overview: The TL;DR concludes with a glimpse into OneDoc's architecture, showcasing its strategic use of open-source tools like Docusaurus and DeCap, coupled with custom elements, to create a tailored, efficient, and cohesive documentation platform for 1mg.