Effective documentation in customer experience
A fair share of technical documentation is in the form of knowledge bases, internal-only wikis, or local files hoarded across file server. Would a single piece of software ever solve chronic inefficiency? I doubt it.
Thankfully, there is hope - a culture of documentation. In a recent product training hosted internally by our R&D team, one of the lead trainers started with a mantra, "your knowledge is only as good as your documentation."
In a similar vein, good documentation spurs a new burst of energy for the team and business partners. A value proposition behind documentation for customer support team traditionally has a lot to do with customer satisfaction, and ultimately cost efficiency by way of saving time. Documentation culture goes beyond these major forces. First of all, it changes the way folks collaborate on problem solving surrounding disconnected knowledge.
The first step in problem solving
To begin with, I created a single, visual architectural overview to identify gaps in documentation to demonstrate my colleagues what potential problems we face with outdated and under-documented knowledge base, which means we constantly struggle through where and how to find user documentation and write all-new content.
Getting other colleagues on board with documentation culture is long haul and incremental steps rather than big bang project.
The next step is to look for a way to create a collaborative writing environment where writers, developers, and designers work on the identical space.
Git for writers
A more drastic measure I tinker with is git-based workflow for writing, which I fear only will draw a blank stare, or reveal more blunt reaction, "Hmm, wait, git is not for writers, but for programmers."
Git is a 'distributed' version control system, which underpins a social coding site such as GitHub or GitLab.
What's wrong with track changes in MS Word, SharePoint or version history of Google Docs? The key difference is that git supports developer workflow tightly integrated with technical documentation and web publishing.
领英推荐
A cool thing about git is that it helps working developers and writers on the same space where code and documentation (release note, how to guides, readme files, configuration and more) exist. Such documentation is super helpful for customer support and troubleshooting.
Git has additional benefits of review process (merge request in GitLab, pull request in GitHub), and data assurance that ensures the cryptographic integrity of every bit of your project. The review process is facilitated in the staging area where commits (similar to changes) are reviewed prior to completing the commit.
Git commit messages are the fingerprints that you leave on the code you touch. Any code that you commit today, a year from now when you look at the same change; you would be thankful for a clear, meaningful commit message that you wrote, and it will also make the lives of your fellow developers easier.
Git-based workflow fits in well for multiple teams on multiple repositories. Imagine you work with Node.js devs, remote management APIs for digital signage, firmware development team, and a couple of data scientists working in Python. With git, we can manage projects in one version control rule set and workflow.
To overhaul the documentation culture, it's helpful to familiarize yourself with the git-based workflow and the plain-text markup language such as AsciiDoc or markdown. Both languages are human-readable notation that puts a focus on writing, not formatting. You can edit it with your favourite text editor. Below is a source file written in AsciiDoc.
Next is the rendered file displayed in GitLab.
As Anne Gentle, prominent author and practitioner on Docs like code, puts it, goals of a docs-like-code framework are;
Now, you get a taste of documentation culture, using Git for writing. The next article will cover the types of documentation in Git repository.
Helping businesses scale global operations with documentation, localization, and CRM strategy | Tech
2 年Here is a highly opinionated view on KB. Darren J. George