Making good documentation easy

We’ve been talking a lot about the how and why of software documentation at Go Ahead Tours. As a new member of the team, finding my way these first couple of months, I’ve realized the key benefit of writing things down: Knowledge-sharing.

Good documentation facilitates communication between developers, designers, and product owners, and paves the way toward a cleaner codebase and happier users. Because Go Ahead values collaboration and continual improvement, taking advantage of these benefits is a no-brainer.

So we’ve been experimenting with different forms of documentation. Our overall aims? To make our work more consistent, reusable, and bug-free, and to allow our team to work together in a seamless fashion.

Here are some of our recent accomplishments towards those goals:

• We’re using TypeScript with our React front-end. Among other things, a type system acts as a handy source of information — really, a form of “self-documentation” — about the expectations of our code. It forces you to be clear, right off the bat, about what values and constraints your code should work with. Even better, when reading another developer’s TypeScript code, you can quickly infer what an unfamiliar function does from its type signature — a combination of the method name and the number and type of its parameters.

Why aren’t React’s PropTypes enough, you may ask? PropTypes do add some type safety but only to a component’s props. With TypeScript, you can also specify what you expect a function to return. Nice, right?

• After creating a reusable library of styled, fully functional UI components using React, we’ve documented and demoed the components in a living style guide via react-styleguidist, a resource that makes it easy to clearly list the types and functions of our props, include descriptive comments, and employ markdown to create interactive examples of UI.

We’re looking forward to using this as a communication tool for discussing design requirements and implementations.

• We’ve created a “core” library to host our models. Not only does this library allow us to import and reuse our basic business models wherever they’re needed, it also gives us a place to state clearly what our models are, what data they contain, and — thanks to TypeScript — what type of data the models should expect to contain.

When using our library, a consumer can look at each model and easily grasp our business requirements. It’s a good resource for everyone, whether it’s someone new to the codebase, a developer trying to understand a team member’s code, or a seasoned engineer trying to maintain and extend the codebase amid a growing collection of customer-facing features.

• We write unit tests using Jest and Enzyme. Tests are a great form of documentation, as they define the expectations for our code, giving us confidence that our code works when we build new features, refactor, and clean up tech debt.

Tests also provide terrific examples of how to share props between components and how and when to make use of functions, edge cases, and more.

We provide evolving, casual documentation via code review. If one team member wonders what a piece of code does, points out room for improvement, offers suggestions for updating a function or variable name, the resulting discussion often provides educational value for others.

With this in mind, we always provide updates on decisions in our comments for the benefit of the entire team, even if we’ve had pertinent discussions in person.

We’re excited about what we’ve done so far, and look forward to continuing to find ways to improve our documentation and, subsequently, our product. We’re also planning to add integration testing to our codebases, expand on our onboarding wiki, and much more.

Stay tuned!