5 Adding Features
Adding features is an absolute joy in programming because these are little gifts that you can give your users that ultimately serve to make their lives easier and, importantly, give an onramp for more people to enter the community. Here are three short stories about new features and how they affect users.
Story 1: https://xkcd.com/1172/
Story 2:
I remember seeing a little story on Twitter once about an exchange between a game developer and user.
User: I was designing my character and I noticed that there is no option for it to have a scarf. Can you add that option?
Dev: Sure! I can get that done by tomorrow :)
User: This is awesome, Thank you! I love the new scarf, but I wonder, can it wave a little as I have my character walk?
Dev: Uh… that’s going to take about six months of work.
Story 3: “I joined The Carpentries because I saw that The Workbench was being developed”
5.1 Introduction
One of the best things about developing a tool for a broad community: there is never a dearth of ideas that will fuel the improvement of the tool. This fact also happens to be one of the worst things about developing a tool for a broad community. The larger and more widely-used a tool is, the more you begin to find that the default features really shape the tool, which shapes what people can create with it.
The workbench was built to be a feature-complete replacement for The styles repository in the sense that the following was true:
- Lessons were comprised of primarily episodes with special pages that aggregate content including key points and images
- Pages within lessons would have links back to their source content so people could edit the pages they were viewing
- Lessons could be writtin in Markdown and deployed to GitHub pages
- Lessons could be rendered and previewed locally
- Lessons could render Markdown from R Markdown
During the design phase (2020–2021), we explicitly focussed on a set of features that would enhance the above features of lessons. The most salient features that were of immediate value to our community were:
- A web template that was tested for its accessibility
- A separate instructor and learner view
- An internal package cache for R Markdown-based lessons
One key about all of these features? As The Workbench was being built, these were all implemented separately. This may not seem like a big deal, but it is worth noting because it gives creedence to the modular nature of The Workbench. As I work on The Workbench I always strive to retain this modularity and ensure that whatever I create does not break the workflow of another (unless I have a very good reason for it).
5.2 The Workbench user interface is a lesson
When building a feature for The Workbench, it’s important to remember that people who use The Workbench may not know how to use R, Git, or GitHub. They will be working with a lesson and members of The Carpentries who have been here for a hot minute might actually be afraid of rendering a lesson locally from the experiences they had with the Jekyll interface.
5.3 Ask not for whom the feature breaks
Before adding a new feature to The Workbench, it is important to consider the answer to a few questions before even drafting the implementation, which are detailed later in this section. These questions boil down to thinking deeply about purpose, users, support, and resources, which are all interlinked. Broadly, features can be thought of in two categories: non-breaking changes and breaking changes. When given the choice, always strive for the non-breaking change.
5.3.1 Non-breaking changes
Most of the features you will encounter fall into this category. These are little gifts that you give to your users when they update The Workbench. Sometimes, they can be as small as an message that is formatted to be more readable. Often times, they are going to be optional flags in config.yaml that will allow the user to customize their lesson just a little bit.
5.3.2 Breaking changes
For example, the transition to The Workbench represents a feature with breaking changes whose needs outweighed the negative impact for some of the users. This was a project whose purpose was to improve the accessibility and maintainability of our lessons for our community. It would impact the users by providing a better interface at the cost of requiring maintainers to fundamenally change their workflows. We were able to provide support for The Workbench because the developer of the system was a paid staff member of The Carpentries. Finally, the resources existed through funding via Chan-Zuckerberg Initiative, the Moore Foundation, The Sloan Foundation, and The R Consortium. Moreover the tools that we used to build The Workbench were well-tested and well-supported.