What Were the Challenges of Our Previous Process?
Things were slower and harder to define in our previous process, as we depended fully on our customers’ varying requirements to determine how to document and what tools to use in the process. This meant that we always delivered documentation in different formats, from PDF documents to files in documentation platforms. As you can imagine, this lack of consistency made projects complicated.
In the absence of complete standardization of documentation delivery, we faced many challenges:
- Disorganization in the version control of documents
- Misalignment of the source of truth
- Difficulties involving developers in the documentation process
- Inconsistency in the review process and approval system
- Slight delay in the update and delivery of the documentation in regards to the agility of software development
- Overwriting in collaborative documents
As technical writers, we know that we must be as fast as the software development process within agile environments of extreme collaboration and continuous deployment. Taking this into account, we found it necessary to implement a Docs Like Code solution at Wizeline, as we knew this would help us to better integrate with the dynamic of development teams.
Looking back at our pain points, we decided we needed to improve our writing processes, search for a documentation strategy, and find an appropriate Docs Like Code solution that would help us thrive in our industry.
How Did We Implement Docs Like Code?
The implementation of our Docs Like Code solution was neither straightforward nor easy. Within the technical writing team at Wizeline, we put together a task force that was responsible for designing and testing tools that best matched our team, our customers, and Wizeline’s high-quality requirements. After implementing the solution, the task force took ownership of training the rest of the team members on how to learn and adopt Docs Like Code.
We explored and tested a range of different tools that could potentially help us reach our objectives, such as:
- Static site generators to implement easy-to-deploy platforms
- Containerization tools to reduce the learning curve of bootstrapping a Docs Like Code solution
- CI/CD tools to automate the deployment of the static websites combined with little manual work
Following the testing phase, we aimed to select the tools that best matched our team’s needs and, of course, our customers’ needs.
In the end, we built the solution using the following tools:
- MkDocs: To generate static websites for general documentation using Markdown and publish the documentation as HTML websites.
- Slate: To generate static websites for API documentation using Markdown and Swagger files and publish the documentation as HTML websites.
- Docker: To containerize a sample Docs Like Code project, thus ensuring that technical writers or anyone who wants to implement a Docs Like Code solution can simply run the containers and have a project set up in seconds.
- Git and GitHub: To control the documentation versions. We also use GitHub Actions to lint and publish the website to a hosting service.
- GitHub Pages, S3 buckets, and Netlify: To deploy the documentation site. (This can be whichever hosting server the customer prefers.)
Our first solution works as follows:
Here’s the flow of the solution:
- Technical writers download the Docs Like Code solution to their local environment.
- Technical writers work on the first version of the customer’s documentation and branding.
- Technical writers add the solution to the customer’s official repository.
- Technical writers add the documentation content (containerized in Docker) to the repository. The Github workflow triggers Vale, along with any other additional automation pipelines.
- The documentation site is published and made available for end-users.
What Are the Benefits of Our Docs Like Code Solution?
As previously mentioned, we initially faced several challenges due to the lack of complete standardization of our documentation delivery. Implementing the Docs Like Code approach delivered a highly beneficial solution by:
- Improving our customer experience with regards to their documentation
- Enabling our team to receive faster feedback from customers and other developers
- Integrating successfully with development teams by using the same tools and development process
- Reducing the cost of using third-party platforms to implement and host the documentation of our customers
- Customizing the documentation presentation by using our customers’ branding
- Standardizing the technical writing process, including reviews and approval systems
- Enhancing collaboration through version control for documents
What’s Next?
After we decided on our solution and shared it with our team, we knew we had to think about further implementation and solution delivery.
In terms of implementation, the next steps in our solution aim to build more specific-case solutions and implement automation strategies into our solution. To achieve this, we are now working on:
- Implementing the site for API references. For this, we are using the Slate static site, which offers the two- and three-panel solutions that work best for API documentation.
- Using Vale for natural language linting, which will automate part of the review process for our documents.
- Implementing authentication layers using scripts and tools such as Firebase.
As we deliver our solution, we want everyone at Wizeline to be part of it! This way, everybody can contribute to the documentation and participate in the writing process. Our final goal is to provide our customers with the best solutions, in terms of both software development and how we present their documentation.
How Did the Solution Impact Our Customers?
We provided the teams with the tools and training needed to help them fully adopt the Docs Like Code solution. The expectation is to continue embracing this approach to best support our customers’ specific documentation requirements.
A business case that is worthy of mention involves a LATAM delivery service application. We implemented a Docs Like Code solution that reestablished the way our customer presented their API resources. This solution combined web development and technical writing best practices. As a result, our customer was able to improve their end-user experience.
Moving forward, we know that the Docs Like Code solution will help us, technical writers, to better integrate with the engineering teams, technical infrastructure, and development process at Wizeline. In turn, it will aid us in achieving our ultimate goal of always providing the best and highest quality solutions to our customers.
This blog was written by Silvia Alvarado and Alejandra Pedroza on behalf of the DocOps and technical writing team at Wizeline.
