Topics in this article:

• Washington DC Department of Buildings
• PDF vs Docs as Code
• The transition process
• Results
• Broader implications

This case study examines the transformative journey undertaken to modernize the Washington DC Department of Buildings (DOB) documentation processes. DOB’s transition from a traditional PDF-based workflow to a Docs as Code process was powered by our open-source solution, DocsKit.

Washington DC Department of Buildings

The Washington DC Department of Buildings is responsible for ensuring the safety, compliance, and sustainability of buildings within the nation's capital. Tasked with overseeing a wide range of activities, from issuing permits and conducting inspections to enforcing building codes and regulations, the DOB plays a critical role in the city's infrastructure and development.

When the Department faced increased turnaround times for construction inspections, resulting in costly delays for builders, DOB partnered with platformOS to build an “inspection marketplace”, a Private-Public Partnership (PPP) that seamlessly connects builders with third-party state-approved agencies.

On the website, built on platformOS's Government Solution, clients can easily find, book, and pay local inspectors. Meanwhile, the authorities benefit from clear oversight with easy access to near real-time information and early warning signals to support building safety reviews.

As a result, the authorities generate revenue and achieve full transparency. Property developers save money due to shorter inspection times, and agencies save time and costs thanks to the seamless scheduling processes.

Since then, platformOS has extended the digital services DOB offers with Certifi, a solution for applying for a Certificate of Occupancy (CofO) and wall checks to facilitate collaboration among stakeholders in the wall check process, with many more services to come as part of our long-term collaboration. 

However, the department's documentation process, traditionally reliant on PDF workflows, presented challenges in terms of efficiency, accessibility, and user-friendliness. To address these issues and better serve the community, the DOB embarked on a transformative journey to modernize its documentation processes, adopting a cutting-edge Docs as Code approach with the help of DocsKit, platformOS’s open-source solution. This article explores the steps taken in this transformation, the benefits realized, and the broader implications of embracing open-source methodologies in government operations.

PDF vs Docs as Code 

The transition from a PDF-based workflow to a Docs as Code approach using DocsKit brings significant improvements in efficiency, collaboration, and accessibility.

While the traditional PDF workflow often involves minimal stakeholder communication and ad-hoc planning, DocsKit facilitates active stakeholder involvement and strategic planning. This results in continuous improvement through frequent iterations and reviews.

Content management in a PDF workflow is typically redundant and scattered. As PDFs are notoriously difficult to update and maintain, a PDF-based workflow often results in outdated information remaining on websites. In contrast, DocsKit centralizes and reuses content, ensuring consistency and ease of maintenance. Theming and customization options are limited with PDFs, whereas DocsKit offers extensive theming capabilities and a wide range of custom components to meet specific needs.

PDFs, though widely used for distributing flyers, handouts, and manuals, present significant accessibility challenges when repurposed for web content. Originally designed for print, PDFs often create a jarring user experience online. They lack navigation features, making it difficult for users to find information, and are not mobile-friendly, failing to adapt to different screen sizes.

For visually impaired users, PDFs pose even greater issues. Adjusting colors and text sizes is challenging, and many PDFs lack proper tab order for screen readers, alt text for images, and long descriptions for diagrams. This makes accessing the content difficult for those who rely on assistive technologies.

PDFs also negatively impact search engine optimization (SEO). They lack structured data, are often large and slow to load, and are not optimized for mobile devices, leading to poor search engine rankings.

In contrast, DocsKit addresses these issues by providing built-in features that ensure accessibility compliance, enhance user experience, and support inclusive design.

Finally, DocsKit provides robust version control, unlike the basic versioning available with PDFs, ensuring a reliable and up-to-date single point of reference for all stakeholders.

Here’s a summary of the key differences:

The transition process

The journey to transition the DOB’s documentation process involved several key steps:

• User research: We began by using our experience in building documentation solutions and facilitating user research to understand the needs and pain points of inspectors, third-party agencies, reviewers, and administrators. This insight was crucial in shaping the new documentation strategy.
  
  
• Stakeholder communication: Engaging with all relevant stakeholders ensured that everyone was aligned and supportive of the changes. Regular communication helped in addressing concerns and incorporating feedback.
  
  
• Planning: A strategic roadmap was developed to guide the transition. This included setting clear milestones and defining the scope of each phase.
  
  
• Iterations and reviews: The transition was implemented incrementally, allowing for continuous improvement based on feedback and iterative reviews. We started with implementing a DocsKit documentation site for all new functional areas of Tertius (for example, the Certifi feature where people can apply for a Certificate of Occupancy), and then we went back to migrating content from the PDFs to DocsKit sites as the process was already established and familiar to all stakeholders.
  
  
• Training: We've built a comprehensive documentation knowledge base for various user groups like reviewers and admins to help them effectively use the new Docs as Code system. The knowledge base includes access to the GitHub repositories' preview, staging, and production environments of the various documentation sites, a developer and editor guide, a style guide with accessibility guidelines, guides for testing and QA, troubleshooting information, and more.

Join our free course to gain a deep understanding of the Docs as Code methodology:

Results

Using DocsKit brought several advantages over the legacy PDF-based system:

• Efficiency: The new system streamlined the documentation process, reducing redundancy and ensuring consistency. Centralized content management allowed for easier updates and reuse across different documentation sites.
  
  
• Theming and customization: DocsKit offered extensive theming options, enabling tailored solutions to meet specific needs.
  
  
• Accessibility and inclusion: Built-in accessibility features ensured that the documentation was accessible to all users, promoting inclusivity.
  
  
• Improved collaboration: The DocsKit system facilitated enhanced collaboration by allowing more stakeholders to be involved in the review process. This inclusive approach ensured diverse input and feedback.
  
  
• Quick updates and iterations: The new workflow supported rapid updates and iterations, ensuring that the documentation remained current and accurate. This adaptability was crucial for maintaining up-to-date information.
  
  
• Addressing real user needs: By focusing on user research and feedback, the DocsKit approach allowed for adjustments to be made as needs arose, ensuring the documentation met real user needs and pain points effectively.
  
  
• Targeted content for each user persona: Thanks to the opportunities offered by online content and single sourcing through DocsKit partials, we could create customized content for each user, allowing them to follow their own user journey from start to finish. In contrast, with PDFs, users had to jump to different pages, which disrupted the user journey.
  
  
• Scalable and extendable: The platform's scalability and extensibility allowed for the integration of additional solutions, such as the platformOS learning management system including video courses and webinars, further enhancing the overall user experience and support.
  
  
• Enhanced searchability: DocsKit’s structured format improved search engine optimization (SEO), making it easier for users to find relevant information quickly.
  
  
• Version control: Robust version control ensured that all stakeholders had access to the most current and accurate versions of the documentation, reducing confusion and errors, and ensuring the documentation served as a single, reliable point of reference for all stakeholders.
  
  
• Sustainability: Transitioning to DocsKit reduced the use of paper-based documentation, supporting more sustainable and environmentally friendly practices.

The Website Carbon Calculator score of the DOB Certifi documentation site

Broader implications

The transformation of the DOB’s documentation process extends far beyond operational efficiency—it brings substantial benefits to the broader ecosystem.

Embracing an open-source Docs as Code methodology streamlines information contribution and management, championing inclusivity and accessibility. This foundation supports a plain language approach to documentation, offering greater clarity for all users.

The government third-party inspector marketplace solution built for DOB actively supports the inclusion of small independent businesses and encourages the participation of minority-owned businesses. Combined with DOB’s accessible and user-friendly documentation, it creates avenues for increased participation from under-represented cohorts. Our holistic PPP approach signifies a paradigm shift, fostering an ecosystem that thrives on collaboration, equity, and openness.

DocsKit is open-source, licensed under the terms of the Creative Commons Attribution 4.0 International License. Separately, platformOS offers a range of services, including setup, hosting, support, accessibility, sustainability, SEO, and performance packages. Leveraging the success achieved with DOB, platformOS is working with other government agencies to adopt an open-source Docs as Code approach to documentation.