When I first started contributing to Kali Linux, I was in my final years of high school and was doing QA tasks. My task was to test ARM scripts and builds, verifying that hardware was working correctly. Just providing a second pair of eyes on things mostly because I had the hardware available. It wasn’t that much work, but due to my inexperience I still needed to be helped through it at first. To educate myself, I started reading the original edition of Kali Linux Revealed along with as much of the Kali Docs as I could.

As I was studying Kali, I was learning about its tools and how they were used. I learned how images were created, what the release process looked like, and all the ways that Kali differed from the various other Linux platforms. As I progressed, I was able to assist with the QA tasks more. I started helping with certain release tasks, verifying if tools worked and that images had all their functionality. I also started helping with the documentation.

Kali Linux was maintained by a much smaller team back then, and as you can imagine there were a lot of tasks that needed attention. Documentation existed, but with so many pages it was difficult to keep all of them up to date and accurate. While I was learning, I would encounter situations where the docs didn’t work as expected, or find grammar mistakes that I could fix. I was good at writing; I enjoyed it, so I started doing pull requests with fixes.

I had never written for anything outside of school before, and that was always just essays to complete assignments. I had no experience with technical writing; I didn’t realize the difference in techniques when reading good documentation versus any other type of online tutorial. I was a consumer, not a producer. But I still wanted to contribute, so I did. I fixed grammar mistakes, I updated terminal outputs and command flags, and I updated anything else that needed refinement that I encountered while I was reading.

I feel like, for me at least, it isn’t obvious when your mindset starts to change. It’s something you look back on and realize. I was simply contributing, doing what I could to improve something that I felt I was good at. I would get feedback from the Kali team, and I would make adjustments based on it. It was different than what I was doing at school, but it didn’t feel like a different class of writing. I eventually was given advice to take Google’s technical writing course. So I did. It was then I realized what I was writing, and who I was writing for.

Technical writing and documentation aren’t just about giving the right commands or steps, as I was doing. What if something went wrong? What if someone’s environment was different? You needed to teach, not just instruct. Because that is what good documentation is: a learning tool.

When you read through how to install a tool or what a tool does, you don’t just want to know what keys to press. You need to know why you’re pressing those keys, what the result of pressing those keys should be, and what you can do when something goes wrong. If you cook, bake, work on computers or automobiles, or any of the dozens of other examples, you should know what I mean.

When I write anything technical, I keep a couple of things in mind. Clear communication that even those inexperienced can understand, and formatting that clearly separates knowledge, instructions, and console input or output. You can never know who exactly is reading your content. They may have a doctorate, they may be in high school, or they may speak very little of whatever language it is you write in. If you make something too complicated, using bigger unnecessary words, assuming someone knows a command and how to use it, or even just assuming that someone has already read your other documentation, then you begin to lose what really makes good documentation. That’s what I learned to love; the feeling I got when I heard from people that read my work and came away from it happy, knowing that what I wrote taught someone something.