Implementing a Simple Web Service Documentation Workflow Today
Blog: The Tibco Blog
In 2002, Jeff Bezos famously mandated that all new applications at Amazon must be built using and exposing their own web services. In 2018, I still haven’t heard of any such memo from any major company that declares those services must also immediately be documented following some set of internal standards. So, consider this your mandate.
As I’ve mentioned previously, poor documentation is the single biggest hindrance to developer success. But what are we talking about when we say “documentation”?
I tend to draw the line between “static” documentation and “interactive” documentation. Both are vital, but they serve different needs and often follow different paths to come to life. But the right processes can simplify the creation of both and not require duplication of effort.
Static Documentation – The Manual for Your System
Static documentation is what you might traditionally call a “manual” – it’s the actual documentation that you write with the intention of being read mainly start to finish. This type of documentation generally consists of tutorials, step-by-step instructions to address a certain use case, sample code, and any other kind of documentation that follows a narrative. Its primary purpose is to clearly explain any esoteric aspects of your system that are not clear to someone coming to it for the first time and help them reach a solution to their problems as quickly as possible. It can also be used to jump-start certain development activities – not only the basics of what your product is intended to address but any aspirational uses cases you think developer customers may find useful.
You must write your static documentation for your developer audience, which means you must first put yourself in their shoes. What are the challenges they’re facing that your product solves? How will your product do it better than the competition? What information do they need to not only get started with your product but to bend it to their needs? What are the most common use cases you expect they will need to solve for?
In addition to onboarding new developers, your static documentation can act as a human-level test against the expectations of your product. For example, if we’re documenting the API for your e-commerce solution, what is the process by which a developer can add a product to the store through your API? First, describe the process, then follow your own instructions to ensure no steps are left out and it works as expected. If the process ever changes, be sure to review these documents and update them to reflect the new version.
Product managers and product marketing managers should be the primary owners of this style of documentation. The engineers who write the code should be the first line of action (we’ll talk about that in a moment), but the PMs and PMMs must be sure to produce the documentation that customers – both internal and external – will use to complete their own work. Though a developer may write the first pass and a technical writer may clean it up to be presented to the public, the PMs and PMMs must be the ones to own the process to ensure they’re meeting the needs of the customers they’re tracking.
Interactive Documentation – Taking it for a Spin
Interactive documentation is a fairly new, yet exceptionally powerful, way to document by showing the system in action. In the API world, the Open API Spec (“OAS”, formerly known as “Swagger”) is the gold standard. Developers producing APIs must document these APIs themselves using this standard. One of the better ways to do this is directly within the code itself using a system like swagger-inline, which allows the developer to write an accompanying Swagger entry in longform comments.
When the code is ready to be released, a script can extract these comments and form the valid OAS for the developers. The resulting spec can then be used to test the compiled code using a tool like Dredd. Once those tests have passed, the spec can be compiled with the larger system-wide spec and presented to the end user through Swagger UI.
Using Swagger UI should replace any static pages that define every endpoint and every field one by one. I think of these as “data dictionaries”. They’re a bear to read and maintain. Swagger UI, on the other hand, serves the exact same purpose – documenting every available endpoint and every possible field and its intended use – but with the added benefit of being able to try out the call directly from the browser without writing a line of code.
As demonstrated, the same spec that drives your Swagger UI documentation can be used to test the service to ensure it actually follows the contract defined by the spec. It can also be used to configure downstream management tools that need to know what services they’ll be managing, like Kubernetes or Mashery.
Not all developer-targeted tools can take advantage of Swagger, though. Design frameworks, integrated development tools, and others can be difficult to document in a way that allows for this level of interactivity. In those cases, consider creating tutorials that can live alongside an active console window or another environment – preferably hosted in the browser – that allows the developer to work at their own pace. You can accomplish this by writing detailed step-by-step tutorials intended to be followed live by a developer, by creating videos that a developer can mimic as they work, or by using a setup provided by vendors like KataCoda, which embeds a terminal window next to static documentation.
The Developer Portal – Your One Stop Development Shop
No matter how you provide your documentation, it should all be consolidated in a single place that makes it easy for developers to find it. The core of your efforts should be your developer portal – the one source of truth for all of your developer-focused materials. All official documentation – including your interactive documentation – should be found here, no more than one click away from the homepage.
As your program grows, you may find other developers are contributing their own tutorials to your ecosystem. If this happens, congratulations – that’s a major sign of developer program success. Encourage and reward these efforts by linking to them from your main developer portal, thus raising their profile with the larger community and helping the rest of your developer audience find vital and interesting information. The same is also true if you use hosted third-party solutions for some of your efforts – be sure you’re promoting them on all of your developer-targeted channels and, especially, on your main portal.
I’m fond of saying, “If it isn’t documented, it doesn’t exist.” If you expect developers to use your tools, you must clearly document every aspect of how they are used and promote it in a visible way. No amount of advocacy, marketing, product development, or evangelism can replace good, thorough documentation.
Summing it Up – A Simple Documentation Process
As you’ve read all this, you may have assumed the developer audience I have been referencing is an external audience – typically partners and third-party developers. In truth, you should create a single developer experience for all of your developer audiences – including the ones on your staff. Doing so ensures you can onboard new engineers to your team more quickly, helps existing developers communicate more effectively, and speeds your time to development of new products.
It’s never too late to get started on improving your documentation. I recommend the following simple process as a baseline. Feel free to adjust it to your needs and to fill in any missing details as necessary. This applies primarily to the process of documenting APIs but, with a little bit of effort, it can easily be adapted to any developer-targeted tool or product.
Rob Z’s Documentation Mandate
- All developers must document their own code. The documentation must live with their code, either in the same repository or embedded in the comments in an extractable way (e.g. swagger-inline), and follow the same guidelines and styles as everyone else in the organization.
- Code reviews must also include a review of this documentation for readability and completion.
- All code must be tested against this documentation, either by a human QA team or using automated testing tools (e.g. Dredd).
- This documentation must be the basis of all other forms of documentation, including static tutorials and interactive documentation (e.g. Swagger UI).
- Static documentation must be updated and maintained as the code is updated. Responsibility for this falls on PMs, PMMs, community managers, evangelists and tech writers. But developers must ensure these documents match the purpose and capabilities of the code they have released.
It’s a deceptively simple process, but it will mean the difference between success and failure with your developer audience.
Leave a Comment
You must be logged in to post a comment.
