API writing
2022
Context
This new app began with 2 APIs for sending and receiving shipment notices to trade partners in Brazil. Ultimately we determined that only 1 API required full documentation because the other was a format owned and distributed by the Brazil government.
API guidelines
To write the content for TraceLink’s API, I started with existing API documentation for serialized shipments in another app. I compared them against the specs for the new API to capture any changes, and then rewrote the element and error descriptions to update the language for conciseness and clarity. The existing documentation was very difficult to understand for anyone who was not intimately familiar with the GS1 EPCIS format. The version for this new app was much easier to understand and used language consistent with other documentation across the rest of TraceLink’s products.
I reviewed the documentation with the Product Manager and Maps Developer. I also extensively reviewed my revised descriptions with the Maps Developer to ensure I did not lose any important nuance in the revisions.
Use case information
In addition to the basic API documentation, I also wrote detailed information about the use case for the API and how the system worked. This API involved multiple apps and the Brazil government systems. TraceLink’s customers rely on TraceLink to understand government regulations and expect our documentation to be the authority on this information, so this conceptual information and use case description is incredibly important.
Processing within government systems
For the API in the format owned and distributed by the Brazil government, I analyzed the specs provided to determine how TraceLink processes the inbound information and carefully documented exactly what information the system looks for in the inbound message, how the system treated that information, and how that information is ultimately displayed. This additional content ensured our customers understood exactly how they were receiving shipment notices from the Brazil government and could have confidence in their data.
Skills
Project management, API writing, use case analysis, processing analysis, applying feedback, XML and EPCIS formats, working within regulated industries, writing for B2B audiences
Tools
MadCap Flare, Confluence, Jira, Excel, enterprise software, SFTP