I have had a great summer with Swift Mentorship Program (SMP) among other things! For people who are curious, SMP is a part of Diversity in Swift initiative that encourages developers to participate in the Swift open source community through mentorship with experienced developers. Its aim is to lower the barrier to entry for folks looking to contribute to Swift projects, which I couldn’t miss out on!
Since I strongly believe good and accessible documentation matters, my learning goal for this summer was to actively contribute documentation to support Swift open source projects. I also aim to further hone my skills as an engineer by understanding more about the projects themselves.
My mentor, who I was lucky to get matched with (honestly, still can’t believe it!), is Erica Sadun (!!) — who has had a wealth of experience with both language design and technical writing. She has authored 30 Swift proposals to date (more than anyone) and participated in countless development discussions.
After our first meeting (with embarrassingly LOTS of fangirling coming from myself), I had started this summer journey with learning all about Swift documentation and what I could do to work towards my goals. One contribution at a time.
Below are some learning notes I have taken throughout this mentorship, which I hope could be helpful to everyone!
- Getting the job done.
- Set your mindset
I find joy in contributing words. I feel pride in knowing my words can be helpful to someone. Remember, your words are helpful and valuable!
Swift and many other open-source projects are a labor of love and care from so many people. It is so powerful to see how much we can do when we work together — we can achieve incredible things. But incredible does not mean lofty! It does not mean they are out of reach, and that you would never be able to make a meaningful contribution to them.
- Start contributing technical documentation
Technical documentation is an underrated skill. In my university at least, we were not taught how to do it effectively. It was always just assumed as something included in the overall expectations of an effective communicator. This work requires an understanding of the code and the ability of condensing it into something a reader can understand.
Reading Erica’s wonderful book got me realizing that documentation is also an art — it requires care, attention, and efforts just like writing code does. The more we practice, the better we are.
I started small, and slowly worked towards more ambitious contributions to bigger projects. Learning by reading through the documentations of these well-documented projects is a good starting point. I made a Notion database of them and note which ones are my favorites, which are active, which are from Apple, which ones are large third-party projects, etc. Then I chose the top 3 projects I was particularly interested in working on for the summer.
I personally am such a big fan of Alamofire’s — theirs is just so well done! They document almost every function, making it so accessible for new developers to use and contribute.
Good examples inspire. But they also overwhelm. And that is okay.
2. Mistakes are encouraged.
Initially, the barriers I have faced when attempting or thinking about making contributions to big open source projects always start with myself. Take Swift as an example, I am a beginner and I already was more concerned with learning how to use Swift well in my work, let alone contributing to Swift itself. Do I even have enough skills and knowledge to participate in the heavily technical conversations from the community?
I was also insecure because English is not my first language. And good technical documentation requires knowing how to choose just the right words — concise and accessible.
For someone who has just started out, these self-doubts are in no way unfounded.
But the more I spent time with Erica and worked gradually on my contributions, I found I can easily shoot the negative questions down and start affirming my own skills. Truly, no matter how much people say “just believe in yourself more” is a cliché statement, it holds true to almost every situation, especially when you are starting out. You are not here because of some dumb luck or mistakes. You are here because you deserve it. And you can always learn and improve — it is in our nature as a human being.
You are not here because of some dumb luck or mistakes. You are here because you deserve it.
In our second week, we took a project as an example, and went through their documentation to understand why theirs is so good. Having not read about the basics of Swift documentation beforehand, I stumbled on my words when trying to point out what made these document comments so helpful. Heck, I did not even recognize the basic differences between \\ and \\\(for context: \\ means a typical comment, \\\ is inline documentation, which you can see when you click on Show Help or Option + Click on the functions you want to read about).
I put plenty of time to make a project list with plenty of notes, but I forgot the most important questions - so what exactly makes a documentation? And how do we write it? How do we differ good documentation from bad documentation?
As someone who takes pride in over-preparing and over-practicing things so everything could be perfect, I was absolutely mortified of myself. Overwhelmed by a lack of preparation, I timidly gave out small and uncertain answers.
Despite this slip-up, Erica was very patient and understanding. She asked such great guiding questions, and neither spoon-fed me the knowledge nor shy away from pointing out that I was not doing myself any favors by doubting my capabilities. And mistakes are perfectly okay and very much needed if you want to learn something.
3. Apply “No Delete” rule.
I remember in one session, I got flustered so much and kept deleting words while trying to figure out what the documentation for this function should be. Erica forbade me to use Delete key, and I had to let my creativity flow through my brainstorming.
Take a look at this example from SwiftLint documentation:
Since report of Reporter currently is not documented, we should document it!
My thinking process looked like this:
Here were the changes I requested for the final PR:
This is similar to the “Yes and…” approach in improv. It is also just true for all kinds of writing. Documentation is just a lot of edits, until it is perfect.
What will happen if we get to freely express our ideas without fear of judgement? Apply “No delete” rule to everything. Be creative, and do not be afraid to be thorough.
4. Communication and Community
Documentation is also about collaboration and community. Remember that you are not alone. You are supported by many people in the community who are so excited to have you with them in this software project.
My mentor gave me advice on how to choose a good project — first, check to see their forums are active. That is, when did the last PR conversation occur? Make sure to scout all the possible communication platforms the community has, and make judgements on how active they are. Another piece of advice I found very interesting is to check to see if the project maintainer “bites”, that is, if they are excited for new contributions. Are they jumping on your PR and making sure you have a good contributing experience? Of course, there are many factors to take into account, but these are great ones to look for.
Erica encouraged me to make as many Pull Requests as possible — I would learn the best when I got feedback from actual project maintainers and also from the process of participating in PR discussions. Some more detailed notes I have taken from these PRs:
- Be pushy and forward in your ask. It was quite painful since some maintainers completely went radio silence when I contacted them to review my PR. People have their lives too. What I need to do is to not take it personally (obviously) and move on. There are always people I can directly reach out to. On that note, take advantage of all communication platforms of the community. Discord is great! Reach out to people. Keep an open mind to learning. Respect their time.
- Quantity is important. But make sure quality goes with it too. But it is totally okay if your contribution is not perfect. Again, mistakes are encouraged.
- I sometimes had doubts that my changes need to follow the standards of the project. But I learnt that I am here to help them just as they help me learn. I am here to help improve their documentation, and I am going to try my best to do that in any ways I can. Rely on PR discussions to help you improve on your PR.
- Never take negative PR reviews personally. Always thank them for their time and calmly take actions.
Finally, I hope you are ready to open some projects and start writing some great documentation! Or even, in Erica’s words, document the heck out of it!
Special thanks to Erica Sadun — I’m so grateful for your wonderful mentorship. Getting to know you as a friend and receiving your guidance this summer has been such a lovely honor of mine! Kudos to folks in Diversity in Swift group for making all of this possible! Also much thanks to Isa, Ivan, Trang, Vee and Linh for their thoughtful insights and feedbacks! ❤️
If you have any questions, you can find me on Twitter, GitHub and Goodreads! I also have a tiny Substack newsletter if you fancy some incoherent half-baked thoughts in your inbox!