How to write good documentation (Theory)

This article is by Anh Pham, an up and coming iOS developer that has been working with Erica Sadun via the Swift Mentorship Program. For those of you out of the loop, the Swift Mentorship Program is a fantastic initiative by the Swift Dev Team that looks to promote open source contributions. As you may be aware, this is a cause that is very close to me. The only reason this newsletter exists is because I wanted people to practice their Swift skills with real life code – no tutorials or perfectly built code. The only way I can keep writing and recording the video exercises is because of amazing people who willingly open source their code.

Anh goes on to write about her experience in the program and how she approaches writing technical documentation. It’s honestly very difficult to be a good developer because it usually means you need to:

  • Write clean and concise code
  • Write maintainable code
  • Test your code manually for bugs
  • Test on different device sizes and/or different OS’s (iOS and iPadOS for example)
  • Add Unit or UI tests, accordingly
  • Write good documentation

Those are ordered more or less according to my own experience, but I’d venture to say many developers have an order similar to mine where writing documentation is the last step. The important thing to remember is that last doesn’t mean it gets cut if we don’t have time. Don’t get me wrong, sometimes comments and documentation aren’t necessary, but when they are you should not skip them. More importantly, writing clear and concise documentation is very difficult because it has to do with you being a good writer. Something that isn’t necessarily a skill you’d expect a developer to have.

Definitely check out the article. Anh’s process is a really good starting point and will show you how to write excellent documentation.