[DOC] Enhancing Docs as Code process

[vagimeli]

What do you want to do?

• [ ] Request a change to existing documentation
• [ ] Add new documentation
• [ ] Report a technical problem with the documentation
• [X] Other

Tell us about your request. Provide a summary of the request and all versions that are affected.

TL;DR

What?: The OpenSearch documentation team is tasked with formalizing and implementing a Docs as Code process. A Docs as Code process streamlines the documentation team's practices, aligning them with modern software development workflows.

So what?: Docs as Code brings collaboration and alignment, quality and maintainability, and efficiency and automation to reduce documentation debt, increase user satisfaction, and improve scalability.

Now what?: The current documentation workflow is siloed, error-prone, and inefficient. Inconsistent information, outdated content, and difficulty with collaboration are causing reduced customer satisfaction, wasted developer and writer time, inefficient updates, and high documentation debt. The OpenSearch technical writers are tasked with driving change to improve the current Docs as Code process.

Business case: Improving Docs as Code for process

The OpenSearch documentation process is siloed, inefficient, and error-prone. Inconsistent information, outdated content, and difficulty in collaboration are causing:

• Reduced user satisfaction: Users struggle to find accurate and relevant information, leading to frustration and support requests.
• Wasted writer and developer time: Writers find themselves wasting time with inefficient content creation, collaboration challenges, reduced productivity, and slow and error-prone updates. Developers find themselves wasting time debugging without guidance, hunting for documentation, referencing outdated or incorrect docs, replicating existing docs, and dealing with technical debt from lack of documentation.
• Inefficient updates: Documentation updates are slow and labor-intensive, leading to outdated information.
• High documentation debt: The backlog of updates grows, further hindering user experience and developer efficiency.

Benefits

Enhancing the Docs as Code approach for the OpenSearch Project offers the following benefits:

• Improved quality and accuracy
• Faster updates because changes in the codebase are automatically reflected in the docs
• Enhanced collaboration between developers and tech writers by working together simultaneously and sharing ownership
• Dynamic content generation
• Increased discoverability through a structured format, enabling users to quickly find relevant information
• Reduced documentation debt because docs are easier to keep updated
• Improved ROI through increased user satisfaction and developer productivity

Investment

• Initial training
• Ongoing maintenance and support

Expected ROI

• Increased open source community involvement in OpenSearch Project
• Improved developer and tech writer productivity
• Reduced documentation debt
• Increased brand awareness and user loyalty

Conclusion

Improving the Docs as Code approach will align documentation practices with modern software development workflows, empowering the OpenSearch Project teams and achieving better open source community outcomes.

Checklist for implementing Docs as Code

• [X] Select a plain markup language (Markdown is the selected language)
• [X] Set up version control repository (GitHub documentation-website)
• [X] Integrate documentation into development workflows
• [X] Collaborate with technical writers
• [X] Automate spelling, formatting, and link validation
• [ ] Standardize template and components
• [ ] Track documentation changes alongside code
• [x] Educate the developers and technical writers on the Docs as Code approach (see presentation Contributing OpenSearch documentation: a quick guide for developers)
• [ ] Monitor and iterate

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.

[vagimeli]

@kolchfa-aws @Naarcha-AWS @hdhalter @bbarani Please review this first draft of the Docs as Code business use case. Before scheduling a kickoff call with @peterzhuamazon and @AMoo-Miki, the tech writers would like to make sure we understand the objectives and goals of Docs as Code from the manager point of view. Thanks for your support, Melissa

[vagimeli]

Action items

1. Work with engineer to add GitHub Actions workflow to development PRs to confirm documentation PR has been created before merging the development PR.

[vagimeli]

@kkhatua FYI