As of last week we are just about half way through Hacktoberfest. Time is just flying by, and I can’t believe how quickly it’s passing. In my previous Hacktoberfest post I wrote about my slightly self-interested contribution to dplesca/purehugo, the theme I use for this blog, and how I used some of Hugo’s built-in functions to normalize URLs that used the .Site.BaseURL variable.

My contribution this week for Hacktoberfest is minor, but it started me on a path to encounter a number of issues with a common theme that should leave me with plenty of work to do over the next few weeks and possibly past the end of the month.

Theme Week: Documentation

There has been a trend over the last number of years for contributors to open source to diversify how they contribute to open source. Code is not the only kind of contribution maintainers hope to receive, and they are happy to receive contributions in the form of documentation, code examples, sample projects, and feedback from first-time users, among others.

For Hacktoberfest week three, I focused my efforts on project documentation, or a lack thereof, specifically from the perspective of a new user. So far during Hacktoberfest I haven’t made more than one contribution to the same project; instead I’ve jumped around quite a bit to different projects that use many different languages and project structures. This project hopping has given me some perspective on the onboarding and getting started instructions of a number of projects, which are critical for encouraging adoption and helping new users get up to speed on how to use or contribute to a project, application, or service. Documentation can also be tricky to get right the first, second, or even fifth time because it is hard to write a document that is useful for every audience, especially if the topic is technical in nature and the author(s) can’t make many assumptions about the audience’s technical background or ability. Many projects deal with this by dividing the documentation in two: one set of high-level documentation on getting the project up and running aimed at users, and another set of documentation that augments and extends this high-level documentation aimed at contributors and developers that provides much more technical detail.

This past week also reiterates the importance of contributing to projects in ways other than implementing new features, writing test cases, or fixing bugs in code. There are so many ways to contribute to open source projects, and one of the best ways new contributors can help a project is to verify the project’s onboarding flow by following basic steps like the project setup information and getting their development environment up and running. These are tasks that established contributors and maintainers do not have to do very often and documentation can get out of date; new contributors are great at spotting problem areas in guides, tutorials, and example code that can improve the onboarding experience and identify areas where further explanation may be necessary that established contributors may not be able to see.

Project One: rust-wasm

I have been excited about WebAssembly since I first heard about the work being done to support it in multiple browser engines. WebAssembly is a binary instruction format predominantly designed for the web (though its success on the web will surely spur adoption in other areas just as NodeJS forced us to rethink possible applications for JavaScript) that can be targeted by many other languages like C++, Rust, Go, and Java, among others. rust-wasm is the Rust initiative to provide compilation for the wasm target as well as support interoperation with existing JavaScript code both shipped in browsers and provided as libraries through tools like npm.

I wanted to get up and running with WebAssembly as a compilation target for Rust, so I decided to read some of the core documentation provided by the rust-wasm team: the Rust and WebAssembly Book. After taking a brief detour to set up a personal Homebrew tap for the wasm-pack tool (which I hope, once the prerequisite Rust version lands on the stable channel, I will be able to contribute back to homebrew/hombrew-core and rust-wasm), I was able to set up all of the necessary project dependencies to start working through the tutorial.

Hello, World!

The Rust and WebAssembly Book bases the tutorial off a project template to get new users up and running more quickly. It spends a portion of the introductory section talking about each file in the template and its purpose in the larger project. When I got to the section describing wasm-game-of-life/src/utils.rs, I was given this explanation:

The src/utils.rs module provides a couple included batteries that we will use later in the tutorial. We can ignore it for now.

— Rust and WebAssembly, 5.2 - Hello, World!

After the reasonably detailed explanations of other files in the project, this section stood out to me as one that could be improved. This section also makes reference to a philosophy of “batteries included”, which I had only ever been exposed to before in Python jargon and that may not be familiar to everyone who has not had a similar exposure, or for whom English is not their primary language and the idiom is lost in translation.

Being a fresh set of eyes on the Rust and WebAssembly Book, I filed rustwasm/book#127 to discuss some suggestions for how this section could be improved without the need for jargon-heavy idioms and to provide more details about the particular module in question. At the time of publishing I have not heard back from anyone on the rust-wasm team, but I am hopeful that I will be able to submit a pull request before the end of the month to improve this part of the tutorial.

Typos and Transcription Errors

Reading through the rest of the page, I ran across the simple error of a duplicated word in the explanation of wasm-game-of-life/www/index.js. I submitted my correction as rustwasm/book#128 and it was accepted the same day. I even received a congratulatory message from one of the maintainers on my first contribution to the project which, as my first interaction with any of the project maintainers, is a nice personal touch that definitely makes me want to to continue to contribute to rust-wasm.

Project Two: Diesel

I have been playing around with reimplementing a currently active Postgresql-backed project using Rust, and discovered Diesel as one of the ORM tools at the forefront of Rust development stacks. As with rust-wasm, I have not used Diesel in any of my projects, so I turned to the getting started guide Diesel provides. It wasn’t long after I got the diesel-cli tool installed that I ran into a discrepancy between the guide and the behaviour of the CLI tool, so I filed diesel-rs/diesel#1891 to detail my expectations along with the actual output the tool was producing, as well as some suggestions for improving the clarity of documentation in a few disparate but related areas of the codebase and guide.

I am of course very grateful for the guide because it is much more approachable - with many code samples and examples - than reading highly technical API documentation or man pages. However, it can be intimidating for a new user if they are following along with the steps in the guide and something unexpected happens; often the new user doesn’t know if they did something in the wrong order or missed an important step, or if the guide is simply out of date and they are not sure how to get around the outdated part to continue their progress. It is also common for code and documentation to get out of sync, resulting in confused and annoyed users. Unfortunately there isn’t a great technical solution to this issue and authors need to always take care to not only update code but also documentation, though Rust’s documentation tests are one example of a tool that can help by ensuring that example code included in comments is up to date and working.

Project: Next

As I am still a new user of rust-wasm and Diesel, I am sure there are still many things I can contribute to these projects, both in terms of improving the onboarding experience for new users as well as other non-code contributions. I also have my eye on a few areas of the guide for Rocket, a web framework written in Rust that was the reason I started using Diesel. I’m hoping to hear back soon about the two issues I filed to improve documentation, and I’d like to take the time this month to shepherd them through to getting pull requests opened and merged. As for this week, I’ll be picking out my next few contributions for Hacktoberfest and might also start thinking about picking a project to stick with for a while now that I’ve worked on a number of projects so far this term.