Kateryna Osadchenko is a technical writer and content designer. She has been a tech writer for almost six years and has delved into various industries and domains. In this article, she shares her experience with adopting DocOps for a payment provider that allows accepting card payments other payment methods, and processing orders in one place through one’s website.
Document operations or DocOps is a set of practices that works to automate and integrate the process of developing and updating documentation across engineering, product, support, and technical writing teams.
Over time, we got a bigger structure, bigger docs, and a bigger need for automation as we developed an ever-growing set of docs to enable and support server-to-server API integration to accept different payment methods and manage transactions. So we’ve got docs, and now we need tech writers on board to create a link between engineering, product, and support teams.
Tech writers ensure that docs are treated as an integral part of the final product or service. They follow key principles while creating docs, which plays a key difference when approaching your API references or technical docs management. The key principles are –
- Accuracy and compliance – You must align with your industry regulatory requirements
- Agility – Keep pace with SDLC and API integrations
- User-centricity – Prioritize ease of use and application
- Collaboration – Work closely with cross-functional teams
While adopting DocOps, we started by identifying the main points –
- How do we align more with our engineering roadmap or software development lifecycle?
- How do we track updates and collaborate across teams more efficiently?
- What is consuming excessive resources in delivering and updating API docs?
- Find out what’s not working or lacking in your docs and seek feedback from teams closest to user issues.
- You need to think about docs as a living breathing organism. You’ve got legacy docs, bits and pieces from different subject matter experts, code, snippets, and tons of different pages and files, all stored in a repository or different places.
We considered the following factors before deciding on automation –
- Initial need – Assess the urgency and frequency of tasks such as docs, code, reviews, editing, and testing.
- Impact of automation – Weight the benefits of automation versus your manual efforts.
- Available resources – Collaborate with developers, subject matter experts, and business owners to make accurate estimations of your efforts and available resources
- Budget and long-term planning – Allocate resources based on budgets and estimation.
What kicked things off
- Streamlining documentation deployment with version control tools in a fitting format. It could be markdown or JSON to ensure real-time updates. It’s virtually impossible to approach automation without using any tool that is already widely used and successful for the software development process. That’s why it’s highly encouraged for tech writers to get on board and get closer to your developers and see what they’re using, how they are commenting, updating, and pushing updates in the streamline, and how Docs can be embedded, implemented, and aligned with processes that already exist. Some of the actions after you set up your streamlined deployment process would be identifying what’s the easiest thing you can automate.
- Link code snippets in Docs directly to the code base, reflecting real-time changes. This is crucial when your Docs are growing and the number of your API references is growing.
- Try out linters to flag broken links, errors, stylistic errors, or questionable constructs in your docs.
- Get a developer or tech-savvy writer on board to drive an advocate for adopting a version of the docs that works for you that fits your needs, resources, and ambitions.
Is there a Bare minimum for DocOps?
While using DocOps, you might wonder if there’s a bare minimum for DocOps. Are we doing enough? Are we doing too much? You might get to a point when you question if there’s anything you can be doing differently, or whenever your organization grows to the point where it’s hard to stay in sync, when priorities change, when teams clash, in terms of priorities and timeframes. Therefore, you might not have too much time or resources to dabble into too much planning; you need to be able to stay realistic but still try to be on the same page with improving the lives of your teams and still keeping in line with tight deadlines, restrictions or limitations that exist and cannot be removed.
All of this depends on the size of the documentation set, how many docs you already have, and the industry that you’re in. One size does not fit all, depending on the use case you are catering to. Therefore, it’s all customizable, directly related, and dependent on your existing structure.
After trials and tribulations, our team of tech writers has come to a realization and conclusion that there are ways that we can step up our tech game, and there are things that we can borrow from tools from the developers.
Tech and API documentation is about adapting to the demands of your rapidly evolving industry, fostering collaboration, seeking feedback, and making strategic decisions on what to automate and what is not important. It’s okay to let go sometimes and not strive for total perfection. As long as you have some base operations set up and working well for you, that’s a good enough start, and it will surely align with your business needs and priorities.
To conclude, tech writers have a unique role in bridging the gap between technology and audience and internally between different teams and business units. By aligning our efforts with DocOps principles and leveraging automation wisely, we can provide a better developer experience, stay compliant with regulations, and keep up with the ever-changing FinTech landscape.