Technical Writing with Google Season of Docs | OWASP ZAP

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.

Selection_407

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.

docAs 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.

tech

 

Final Deliverables

API Docs URL: https://www.zaproxy.org/docs/api/#introduction

GitHub URL: https://github.com/zaproxy/zap-api-docs

Selection_394

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.

Selection_420.png

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>

Selection_423.png

  • 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.

toast.jpg

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. 

oxford comma.jpg

 

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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s