Google Season of Docs is a program giving technical writers an opportunity to contribute to open-source projects. I was selected as the technical writer to the OWASP Foundation to create the API documents for one of the world’s popular security testing tool. ZAP !!
Although I have written articles on many occasions, I was skeptical about the work ahead. Because I’m not a technical writer by profession, and following is the idea I had back then when I thought about technical writing.
Nevertheless, the 3 months turned out to be a rewarding experience, and the blog below outlines my experience and learnings out of the program.
Problem
ZAP has an extremely powerful API that allows us to do nearly everything that possible via the desktop interface. However, to effectively use the APIs, a good understanding of the UI is needed. This is because most of the APIs directly correlate to the user interface of the ZAP. Therefore my proposal was to create detailed API documentation and to document the high-level API orchestration scenarios.
Initial Objectives
The initial objectives were to create the OPEN API specifications for the 380+ ZAP APIs. The OPEN API definition will be used to autogenerate an ASCII doc. The doc will be enhanced with the high-level use case examples on how to orchestrate each APIS.
As I deep dived into the community, it’s was clear that the users heavily used client SDKs to automate the process. Thus, ASCII doc will not be a good option to display such details. Therefore I started looking for alternatives. The following are some interesting API documentation platforms in the wild.
- Slate
- ReDoc
Technology for Documentation
ReDoc offers an interactive API documentation platform but the support for high-level docs is poor. Thus we selected Slate to document the APIs. Slate has a three-column approach where the middle column will have the content, and the right column will have the sample code. Slate also follows the docs as code philosophy; thus, I can write my documents using the same software development tools.
So with the right technology in place, I started to write the documents.
Final Deliverables
API Docs URL: https://www.zaproxy.org/docs/api/#introduction
GitHub URL: https://github.com/zaproxy/zap-api-docs
Achievements
- Introductory content on the basics of the APIs and ZAP.
- Code samples in Python, Java, and CURL commands.
- Contribution guidelines for the community (Grammar, Language Style,etc.)
- Auto-generated OPEN API based code samples for ZAP APIs (380+)
- High-level docs on how to orchestrate ZAP APIs to perform Spidering, Scanning, retrieving results, authentication, and advanced configurations.
Community Response
We had a good response from the entire community with regards to how the APIs were documented.
Lessons Learnt.
- Open-source documentation needs more love! There are such awesome functionalities that need proper documentation. Even a small contribution can go a looong way. <pun intended>
- The open-source community has really good people. This is the first time I worked with such a large community and to my surprise, everyone involved is super nice and helpful.
Pointers for new contributors.
Defining the contribution and style guides gave me a good knowledge of the art of technical writing. The following books can give a good introduction to the process. TBH, I didn’t even know the writing community was divided by the oxford comma until I started reading.
Future Work
The three-month program was very rewarding gave me a good perception of ZAP and the technical writing process. In the future, I’m intending to contribute more to ZAP blogs and code to spread the word.
Final Words.
Besides, this would have not been possible without the amazing mentors, @Simon Bennetts , @Rick, @Ricardo Pereira. Thank you for your guidance and support.
