Go-to-Market Documentation

Documentation is a critical aspect of the go-to-market (GTM) strategy, pivoting in change management, reducing support burden, and enhancing product discoverability through semantic search.

1. Change Management: Documentation is a vital tool in managing change, particularly when launching a new product or service. It provides a clear and comprehensive guide for all stakeholders, ensuring everyone understands the new processes, features, and functionalities. This reduces the risk of miscommunication, errors, and resistance to change, thus ensuring a smoother transition and a more successful product launch.
2. Reducing Support Burden: Comprehensive, user-friendly documentation can significantly reduce the burden on your support team. By providing customers with detailed guides and FAQs, you empower them to solve common issues independently, reducing the number of support requests. This not only frees up your support team to focus on more complex queries but also enhances customer satisfaction as users can find solutions quickly and easily.
3. Increased Discoverability through Semantic Search: All manuals will be indexed by semantic search engines, making your product or service more discoverable. As users search for solutions or information related to your offering, your documentation will appear in search results, increasing visibility and attracting potential customers. This will also include generative ai, chatgpt-type functionality built automatically in your documentation before the end of 2024.

Who Writes the Docs?

The Developer Enablement team is unlikely to be large enough to write and maintain the documentation for every Paved Road product. In order to scale it is recommended that the individual engineering teams be responsible for their own documentation.

There are several reasons why individual teams being responsible for their own documentation is beneficial:

• Expertise & Understanding: The team that develops a service or product has the most comprehensive understanding of it. They can provide detailed explanations, feature workings, and accurate usage methodologies.
• Time Efficient: Teams seen as 'experts' are able to populate documentation more quickly and accurately than those who are not familiar with the project or product.
• Boosts Ownership: Taking responsibility for the product documentation enhances the team's ownership of the product. This can lead to better product care, improved quality, and faster improvement turnarounds.
• Consistency: Every team has unique dynamics, decision-making processes, and operational methods. When teams document their own services or products, they maintain a consistent language and tone, which makes the documentation easier to follow.
• Faster Updates: The team that implemented changes in product or service functionalities can promptly mirror them in the documentation, keeping it current and relevant.
• Improved Skillset: Documenting their own work can help teams develop or improve their technical writing skills, which are highly valuable soft skills in the tech industry.
• Reduced Miscommunication: Delegating the documentation process to a separate team can introduce an extra layer of communication and potential misinterpretation. Having the same team handle both development and documentation mitigates this risk. 

Role of Developer Enablement Team

The Developer Enablement team should offer three tiers of service for documentation to engineering teams rolling out to tools, services or features.

Basic Tier: Self-Service

The Development Enablement teams should offer a collection of best practices, guidelines, tools, and resources designed to assist you in developing high-quality, user-friendly documentation. 

Documentation Best Practices Checklist

Creating quality documentation from scratch varies depending on the complexity of the tool or service. However, it is important not to underestimate the effort and time needed to create good documentation.

Plus Tier: Consultation

Documentation consultation is a service that focuses on providing feedback and suggestions to improve your documentation. It is a collaborative process that involves the client and your Developer Education (DevEd) team. They will use the Documentation Best Practices Checklist. It is a proactive approach to ensuring that your documentation meets high-quality standards and is user-friendly.

Level of Effort

Workflow

1. Initial Consultation: Begin with a 30-minute consultation with your Developer Education (DevEd) team to discuss your specific documentation needs. To prepare, complete Step 1: Product or Feature Overview. This consultation will focus on Change Management and how effectively targeted documentation can impact your goals.
2. Detailed Documentation Audit (3 hours): The DevEd team conducts a thorough audit of your existing documentation, using the Documentation Best Practices Checklist and the Product Documentation Playbook. This audit identifies improvement areas, ensuring your documentation is detailed, comprehensible, and easily discoverable.
3. Feedback Consultation (30 mins): Following the audit, a feedback consultation occurs where the DevEd team shares findings and suggests improvements.
4. Building Documentation Site (25 hrs for end-users, 10 hrs for the internal team): Post-feedback, you will embark on building the documentation site. This task involves creating new content, revising existing content, and organizing everything based on the feedback received.
5. Iterative Review (30 mins): After establishing the documentation site, the DevEd team will conduct an iterative review to verify that all feedback has been incorporated and that the documentation adheres to the high standards set during the audit.Benefits

The documentation consultation service ensures that your documentation is clear, concise, and effective. It helps in creating a positive user experience and can lead to increased user adoption of your product or service. Additionally, the service can save you time in the long run by reducing the number of support requests and improving the efficiency of your team.

Premium Tier: Full Service

With the premium service, your Developer Education team will aim to provide comprehensive documentation support, strictly adhering to industry best practices in documentation. They will partner with your Subject-Matter Experts to build or update your documentation site with rich, targeted content, ensuring an enhanced user experience and smoother adoption of your product.

Level of Effort

Workflow

1. Initial Consultation: A 30-minute consultation with your Development Education (DevEd) team to discuss your specific documentation needs.
   • To prepare for this consultation ensure you have completed Step 1: Product or Feature Overview
   • During this consultation we will spend significant time reviewing the key points of Change Management and how documentation can have the most impact based on your goals.
2. Detailed Documentation Audit: A comprehensive audit of your existing documentation, performed by your DevEd team. This task does not require any time commitment from your side.
3. Engineering Knowledge Transfer: A 3-hour session for transferring knowledge from your engineering team to your DevEd team. This ensures that our team fully understands your product or service. These may be broken into two 90-minute sessions.
4. Building Documentation Site for End-Users: Creation of a comprehensive documentation site for end-users, requiring 5 hours of your team's time and 25 hours of your DevEd team's time. We recommend having a Slack channel where we can exchange context and feedback as we make iterative changes.
5. Building Documentation Site for Internal Team: Creation of a dedicated documentation site for your internal team, requiring 8 hours of your team's time and 2 hours of your DevEd team's time.
6. Iterative Reviews: Regular reviews of the documentation require 2 hours of your team's time and 2 hours of our DevEd team's time. After they launched the site, we expected continued iterations during your alpha and beta phases based on user engagement and questions.

Once the project enters General Availability (GA) mode, the documentation ownership will be transferred to your engineering team. This means your team will be responsible for maintaining and updating the documentation.

Recommended Documentation Sections

If you are creating documentation for your end-users of a new product we recommend you include the following content in your documentation.

• Overview of Product Information: Understanding the Product and Its Importance: This section should clarify the product’s purpose and significance in a manner accessible to individuals regardless of their expertise level. It is crucial to present the product's value and utility succinctly, ensuring that its impact and relevance are understood without necessitating specialized knowledge.
• Foundational Information: Before using a new tool or service, it is important to identify the critical information users need for a smooth experience. This includes determining whether familiarity with a specific language or framework is required and directing users to appropriate resources for acquiring foundational skills. The goal is to provide users with the necessary understanding to use the tool or service proficiently.
• Quick Start Guides: Reducing the entry barrier and providing clear, step-by-step instructions for immediate start-up are key. This strategy should avoid the need for users to sift through extensive documentation by offering concise guidance and, where possible, a scaffolded project or template. Quick Start guides should be customized for different user personas, including specific languages like JavaScript, Python, and Java, to ensure a personalized and efficient onboarding process.
• Frequently Asked Questions (FAQs): Documenting each question received is a vital strategy for enriching the FAQs section, making it an invaluable resource for future users. By compiling every inquiry, a comprehensive knowledge base is created, addressing common concerns and challenges. Furthermore, leveraging AI, such as ChatGPT, to refine these FAQs ensures that the content remains relevant and responsive to user needs.
• Comprehensive Reference Material: The reference section should offer an exhaustive list of materials related to the project, including memos, recorded presentations, and other pertinent documentation. This repository is an essential tool for deepening understanding of the project, providing insights and information that supplement the core documentation.

Types of Documentation

Platform Consumer Documentation

Documentation for end-users of your product or service.

• Introduction: This typically provides an overview of your product or service. It may include features, potential benefits, the problems it solves, and basic requirements to start using the product. It's like providing context or a brief description of what the product is and how it is valuable to end-users.
• Getting Started: This serves as a beginner's guide for your product. It provides instructions on how to navigate through the product, fundamental features, and initial steps for set-up. Its focus is to help the users become acquainted with the product and start using it with minimal assistance.
• Concepts: This section generally deals with more in-depth knowledge about the product, such as system design. It could include explanations of complex features, the logic behind certain functionalities, or background information that could help users understand the product better, as well as debug issues.
• User Guides: These provide step-by-step instructions for accomplishing specific tasks using your product. User guides may be task-oriented, such as "how to set up your account", "how to reset your password", etc. They usually include a lot of screenshots and are extremely hands-on.
• Reference Documentation: This section provides detailed technical information for interacting with the product in a more advanced capacity. It includes API guidelines, instructions for using client software, release notes detailing product updates and improvements, as well as a glossary explaining industry or product-specific terminology.
• FAQ/Troubleshooting: This documentation includes a list of common issues that users of your product might encounter and how to resolve them. An FAQ (Frequently Asked Questions) section typically includes both general questions about the product and technical inquiries. Troubleshooting guides provide a constructive approach to resolving common issues or procedures to diagnose problems.

Team Documentation

This is the set of documents, policies, procedures, and standards intended for internal team members. It can include guidelines on code consistency, best practices, procedures for testing, and substantive details about the overall project or specific technical aspects. It might also consist of the team's mission, vision, roles, policies, and procedures.

• Project Tracking: Includes planning and task management tools like Jira. It outlines task categorization, priority determination, assignment procedures, and status tracking to streamline project flow and improve team transparency.
• Meetings and memos: These are often the documentation of key decisions, new strategies, planned features or enhancements, and meeting summaries. Meetings and memos provide additional historical context and demonstrate efforts to share, farm for dissent, and gather feedback.
• Dashboards: Dashboards are documentation designed to display data, track progress, and monitor a project's health visually. They can be updated in real-time and provide quick overviews of critical metrics, such as issue tracking, project status, and project performance.
• System Architecture and Design: This includes documentation of the software or system’s structure and details about how its parts interact. This could also entail data models, data flow diagrams, class diagrams, and other artifacts to understand the software design and architecture.
• Development Environment: These documents contain information about the infrastructure where the codebase is running, such as software versions, operating systems, hardware, tools used by developers, and more. This will help new team members to quickly set up and understand the required development environment.
• Runbooks for Oncall and Operational Issues: A runbook is a detailed procedural manual that explains how to carry out a routine operation. It's like a checklist for the operator who needs to resolve a problem. Runbooks will outline how to restart services, free up disk space, check the health of services, and what incidents require escalation.
• Stakeholder Communication: Guidelines or templates for communicating with stakeholders or clients, including processes for regular updates or product demos.
• Incident Reviews: This documentation provides structured evaluations of significant incidents during product development or operation. It outlines the incident cause, response taken, improvement areas identified, and the preventative measures planned for the future, promoting continuous learning and improvement.

The Future of Documentation in the GenAI Era

As we start using more advanced search methods, like semantic search which understands the meaning and intent behind words, the quality of our documentation becomes even more important. It's like feeding information to a smart system: the better the information, the better the results. This means our content, meetings, and overall context must be well-managed and up-to-date, especially as we start using more advanced AI solutions. It also highlights the need for good organizational skills, including the ability to classify and categorize information effectively. In simpler terms, we need to make sure our content is not just good, but also well-organized, so that our advanced search systems can understand it and deliver the best possible results.