Beginning a Docs-as-Code journey
As a newly minted tech writer, I’ve had the pleasure to be given my first project in the software department: organize internal documentation. When you have guests come over, cleaning the rooms becomes a mad dash. And as I would expect, if external documentation is the polished, spick-and-span room where your guests are visiting, the internal documentation looks like the closet crammed of stuff.
My manager has a vague goal: to make our docs look “like Microsoft’s”. Is it overkill for *just* internal documentation? I don’t think so, because most of the formatting can be automated, and a good UX is necessary for productivity.
I was surprised at how difficult this project would be. My manager has a goal, and an inkling of how to go about it, and I have to figure out the details. He has the right idea, that a tech writer engages in investigative journalism, who must pry into the private workings of recalcitrant developers.
He probably underestimated how long it takes for a tech writer to win the trust of subject matter experts (SMEs), or how long it takes for any journalist to cultivate relationships when they need to go for the scoop. On top of that, a new graduate simply has zero understanding of the industry.
The company employs tech writers already, which is a team I will call TechNotes, but they are concerned with the application’s end-user audience. I’m the first developer-focused writer, as developers are a separate audience that has to be catered to.
Since I’m fresh-faced out of college, I have all the shiny ideas and no practical experience to make things happen. I also hoard research that almost seems irrelevant. Instead of doing my job properly, which is to extract information out of developers who don’t feel like sharing, I decided my time was better spent creating a pitch.
The plan:
- Get an idea of past precedent and current processes
- Find allies who are interested in good documentation
- Find people with the motivation and skillset to make it happen
- Automate as much as possible
- Write content
I listed the steps in sequential order, but it’s more like doing #1-3 at the same time, a little bit of #5 until you realize that automation would make content creation redundant, and formulating a plan for #4 in the meantime.
Automation #
Efficiency: removing human error and providing templates so people don’t have to think.
Management would prefer that DevOps focuses on the product instead of getting into the publishing business. Yet if they want those shiny release notes to be delivered on time, hiring more writers isn’t going to cut it.
TechNotes has a rigorous publishing process for release notes, video guides, user manuals, and a few public API endpoints. There are tools like Madcap Flare for topic-based authoring, composing and translation, and Snagit for screenshots. But boy-oh-boy, the workload in the future is going to increase massively.
Disconnect #
Before we even get into docs-as-code, I was wondering how we could optimize the internal documentation process. While explaining the definition of docs-as-code is simple enough, it’s mostly a technical writing industry paradigm. Developers have been writing comments in their code for eons, so it’s not a new idea to house documentation and code together. Docs-as-code is more a mindset for the writers, who are rumored to be so fearful of technology that they still use typewriters…
However, it was also apparent that Product Management (PM) was enforcing documentation to go on an internal wiki. The wiki is available to everyone in the Product Development department which includes tech writers, UX designers, customer support, QA, etc. And unlike open-source wikis which are fueled by volunteer passion, enterprise wikis quickly rot if it’s not part of someone’s job responsibility. Libraries need librarians. Would you trust the general public to put books away in their proper place?
Since developers are forced to write using “normie” WYWISYG editors which are cumbersome and not related to their main job, and current writers lack the bandwidth to learn API documentation (even though they want to), and you have a wiki that is “open to everyone” but really means “nobody owns anything,” it becomes a mess. We have eager employees who want to take their skills to the next level, a time ripe for documentation overhaul, but no clarity or direction.
The company has a robust focus on customer support and the non-technological end user. The software product is the backbone of daily operations, but its creators aren’t given the same attention. This lopsided attention is quite unfair.
Developer Relations #
To be honest, I have no idea how I found out about Developer Relations (DR). I just happen to be a voracious Googler with good memory, so the phrase caught my eye. I believe I first heard about “friction,” the pain points of a user’s experience, and then about how software engineers should log their “developer journey” as they do their job.
When I introduced docs-as-code and Developer Relations to my manager, he wanted me to present my pitch to the rest of the engineering leads immediately. Being a former developer himself (now stuck with the job of herding cats), he was pretty excited.
DR and Developer Experience (DX) is the newest trend following the tails of User Experience (UX) and Customer Relations (CR). If I had to define the whole thing, I’d say that DR is about addressing the gap between extroverts and introverts. I don’t know if this is common sense, but computer programming attracts a certain type of personality that tolerates loneliness more than most (hey, writers tend to be hermits too…).
You can go to the dev rel website to read more about it, or search on LinkedIn for job descriptions. At the time of writing, DR doesn’t have a clear career progression. Some would say it belongs to the Marketing Department, or Engineering, or Management.
I think it’s a totally new team. Sure, it can belong to Outreach, or the Learning & Development Branch, or the Knowledge Management Branch, but it’s specifically for computer science and technology. Tech giants like Microsoft have office hours. For anyone nostalgic about university, how surprising would it be if your corporation had a virtual campus system? DevRel is responsible for maintaining a developer community, such as moderating technical discussion forums, hosting workshops, and providing integration help with the product. It’s a new ballgame that traditional customer support can’t handle.
Initially, I was hired to help reduce the amount of questions that engineers have to answer from other engineers. The caveat is that at this company, people prefer to call rather than text. Also, we know that person, someone who, for whatever reason, can’t be assed to rEaD tHe mAnUaL, even if that manual is a perfectly concise, relevant and well-written masterpiece.
What’s more important is to set up a system that can accommodate all learning methods. “Reducing the questions asked” is not a metric that works. Rather, it’s about increasing the quality of discussion. Of course great documentation is a baseline, but we want the community to chip in. One of the engineers asked about a Q&A forum, while a totally separate engineer has been trying to get people to adopt a platform for public discussion.
Bootstrapping a Q&A forum isn’t an easy task. You need community managers for that stuff. The only way to drive adoption is to have people who believe in a grander vision, a vision that things can be better. The documentation is not just docs, but a gateway to the developer helpdesk.
My university library website has a list of librarians and their specialized domains. Writers can contact a librarian who has the knowledge to help with their thesis.
At a large company, we should have an index of all the teams that exist and their technology stack, right? No, we don’t have that info. To find help, you have to do a combination of searching across multiple platforms and asking people for emails.
Convincing others #
It was easy to convince the engineering teams about docs-as-code, given that it’s all about making their workflow smoother.
The hard part is convincing everyone else. If a company only has software as a side branch, and the money maker is from consulting, how do you tell them to invest in what basically seems like training your competitors? How do you tell them that software culture, having stemmed from the fields of physics and computer science, is inherently open-source?
As terrible as the COVID-19 pandemic is, the shock accelerated sentiment for medicine to be open-sourced. While we want to reward innovators for their hard work, we want to reap the benefits of transparency. Smarter, technological advancement and open communication is a facet of our global welfare. Remote work is a permanent fixture, and asynchronous communication through docs, cheatsheets, and videos are required in greater numbers.
I tried to explain docs-as-code to the manager of TechNotes, who relies on the current process, but it was too “low-level” for him. He got a bit defensive: “We have an established process, and it can’t be circumvented. Also, what you’re talking about is just internal and only for your scope. It has nothing to do with my team. Why is the legal team even listening to this?”
Docs-as-code is a disruption of the status quo and a disruption to culture. How would we enforce the discipline to create new rules and standards? It was discouraging to get shot down, but actually, the other teams privately sent feedback to my boss, so they were interested in hearing the rest. Ultimately, I think people will understand the benefits in time. I will continue pushing for Developer Relations until I die.
- When the intellectual property lawyers need to talk to individual contributors, such as developers who may be low on the food chain, who is going to be their connection? DevRel.
- When a business analyst needs help using the company’s own software in a more technical manner, where are they going to find the videos and workshops related to it? DevRel.
- When an external software engineer is evaluating a product and ease of integration, what will convince them to recommend ours? DevRel.
- When the tech writers want to automate their process, and they need help pitching to the engineering team, who are they going to ask? DevRel.
And for goodness sake, we need to stop manually writing out API specs, twice. First by the developers, who send a Word doc of a JSON dump to the tech writer, who then has to parse it and insert it into Drupal CMS. Why isn’t the writer filling in the source themselves?
Progress is slow #
Hopefully, I will have more updates in the future. Currently, we are debating between hosting the docs website on SharePoint or Azure, even though they are both owned by Microsoft. I am totally not used to corporate overhead. 🤷
Future considerations: #
- Training tech writers on Git
- Review cadence between engineers and integrated tech writers
- Recording the rationale behind every decision
- Make sure everything I do has manager approval and I don’t go out on my own… (this is very hard for me, I’m supposed to be a journalist, right?)