A Technical Writer’s Experience with Stoplight
Documentation has always followed the path dictated by the product it supports. When software was delivered as disks in a box, printed manuals shared the space. When software moved online, hosted documentation became the norm. The formats and delivery methods changed, but the basic goal of explaining software did not. Technical writers have to collaborate with a variety of other teammates and the actual API writers to get the job done.
What has changed dramatically over time is the complexity of the information needed to support products. While many companies work hard to simplify their user interfaces so documentation is superfluous, almost everyone understands that an API without documentation is, well… just lines of code that perhaps only the creator can decipher.
This realization has elevated the role of technical writers from ‘nice-to-have’ to a critical cog of the API lifecycle. Technical writers find themselves working alongside developers, using the same tools, combing through JSON and Javascript, and looking for ways to combine product overviews and how-tos with API descriptions, code samples, and mocking.
And because APIs rarely exist in isolation, technical writers suddenly have to reconcile API documentation with their traditional product documentation. Just like printed manuals did not transfer to hosted documentation, traditional documentation tools typically don’t provide the API experience that developers want, and in general, my experience has been that most API documentation tools are not designed to handle large content sets that focus on general product use.
From my now almost year here at Stoplight creating API documentation for technical writers (and my 20+ years in the industry), I’m pleased to say that Stoplight Platform lets you do both: publish high-quality API documentation and how-to information from the same Portal.
My Stoplight Experience
I came to Stoplight with a solid background in technical writing. I had a general understanding of Open API and API tools but was certainly no expert.
In the past, I dabbled with Dita in technical writing, and that was my chosen authoring framework and Dita Open Toolkit plugins served my publishing needs for years. I love Dita, but it’s such a heavy lift to implement, maintain, and grow.
I was excited about the new opportunity because the team at Stoplight uses its API design, governance, and documentation platform to deliver technical content to our customers. I was excited about representing the technical writers who use our tool, so I dug right in.
Here’s some of what I’ve learned.
Markdown is Amazing
After Dita’s rigid adherence to the Oasis spec, I welcomed the simple formatting of Markdown. Sure, there are things I can’t do, such as reuse doc snippets or enforce content types (tasks, concepts, etc.). But Markdown forces me to write as simply as I can. This can only stand to benefit the consumers of my documentation.
Markdown has almost no learning curve. As a manager, I spent many hours training even the most senior writers on how to author in Dita, and when necessary, how to work around its constraints. When Markdown falls short, Stoplight-flavored Markdown often fills the gap.
Strong Git Support
I’m a believer in using Git for content management, and Stoplight tightly integrates with the most popular Git providers.
With a few exceptions, I can use Stoplight Studio to do almost any Git task I need. Two gaps I have noticed so far: one, I can’t resolve merge conflicts in Stoplight; second, I can’t “refresh” my content branch with updates from our main branch. I manage these tasks outside of Stoplight, but both gaps are currently on the roadmap that we hope to amend in the future.
Automatic, Yet Controlled, Publishing
After years of wrestling with DOT plugins to publish content, Stoplight’s automatic publishing is perhaps my favorite feature.
Stoplight uses webhooks to automatically publish content pushed to branches. You decide which branch is visible to either your internal or external user base. The rest of the branches are visible to project members. One of my favorite features is sharing work from pushed branches with technical reviewers. It’s so easy to select my branch, see my pushed content, and direct my reviewers to it. Truly, so easy!
In the End
Overall, so far I’m extremely pleased with my Stoplight experience as a documentation use case. And for those looking for more documentation tips and guidelines, I highly suggest checking out our documentation best practices guide. After all, can an API even be used without good documentation? It’s with solid API documentation and technical writing best practices that developers first experience an API and get to know its functionality.
And while we offer many other features to support the API development lifecycle, I’m obviously biased towards the documentation feature! If you’re an API technical writer, let me know what you think of using Stoplight.
