Hi, I’m Dan Cox. I’ve been creating tutorials, videos, and other guides for Twine for over six years. I’m also the managing editor of the Twine Cookbook project.
Soon after joining the Interactive Fiction Technology Foundation’s Twine committee last year, I started talking with other members about wanting to collect examples of Twine code into a central place. I learned that there had already been a proposal to create a Twine Cookbook along the lines of the Inform Recipe Book or [Ren’Py Cookbook][renpy-cookbook]. The proposal was similar to what I was thinking of, but also involved covering many of the common problems in Twine.
After discussing different ways it might be done, Chris Klimas proposed looking into using GitBook as the format and to host it on GitHub. Iterating through different possible designs and layouts, we settled on grouping by topic the solutions for each story format that is built into Twine. After starting with over a dozen initial entries, we planned to have rolling updates every few months where parts could be updated and new examples added as needed.
As of late 2018, we are celebrating our first full year of running the Twine Cookbook. It is officially at version 1.0, but the current version represents multiple updates by a half-dozen contributors and hundreds of hours of work in creating and maintaining different topic areas across now over 130 pages of content.
Lessons
I often use the terms “running” and “managing” to describe my role with the Twine Cookbook. I set its rolling deadlines and try very hard to meet them. I do a full editing pass on all content, and I often prompt or ask other people to contribute code, documentation, and their ideas for how to improve it. The content itself has come from many different regular contributors like Greyelf, Chris Klimas, and Thomas Michael Edwards who provide their own feedback on its content and how it might be improved.
1) Open means open.
As an editor on the Twine Cookbook, I try to be transparent about its changes, deadlines, and how I handle code commits. Everything is done in the open, and that means that anyone can propose any changes to any section. Those suggestions are still filtered through other users, and I ultimately make a decision about how feedback is included, but the openness of the Twine Cookbook means that we listen to everyone.
2) Compromise.
While listening to feedback from different sources can be helpful, balancing that feedback against present and future content demands is another important challenge. As an editor, I have to remind myself that I cannot make everyone happy—including myself. Often, I will want to keep picking at entries to try to make things as perfect as possible. Others, I know, will often propose solutions that are more efficient or optimized for certain problems.
All of these, including my own opinions, have to be balanced against the overall needs of the project. While I am “running” the project, I am highly open to what others tell me and how they would approach different topics. I don’t always use their feedback, but I always try to listen to both what they are telling me and what theme or message might be behind it. Solving these problems is as much a part of being an editor as trying to clean up code and fix punctuation.
3) Don’t try to cover everything.
Early on in the Twine Cookbook project, the committee had conversations about what should—and should not—be in the Cookbook. These conversations revolved around what were considered common solutions on the one hand, and not trying to include hundreds of lines of code on the other. In the end, we reached a compromise that examples would go into the Cookbook as long as they were to solutions to frequent problems and were something someone would think to find in the book. Then, of course, people stated asking for more complex and advanced examples.
One of the constant struggles of writing tutorials and documentation for Twine—and this comes from doing this for years now—is that what many consider “simple,” just as many do not. The general assumption of the Twine Cookbook is that anyone reading an entry does not have advanced knowledge of CSS and JavaScript. They are looking for a solution or inspiration for a future project. They might not know what functionality does, or even that it exists at all.
At the same time, there is a strong pull to try to cover many of the things that browsers can do that Twine can support through JavaScript. The general reply I give when people ask what Twine can do is “anything a web browser can do,” which to an extent is true. As long as it is supported in JavaScript, Twine can do it. However, that does not mean that advanced functionality like gamepad support and virtual reality that have APIs in modern web browsers need Twine Cookbook entries. While people can use those in their projects, not that many Twine users would be interested, and other libraries exist to simplify many of the issues that would bloat the Cookbook to explain in detail, such as cross-browser support and differences in API.
4) Be open to change.
While being open and willing to compromise may seem to cover many of the challenges of being an editor for an open-source project, one of the most important lessons to learn is to be open to change. Finding a compromise can be important, but so is a willingness to change previously-established rules.
When the Cookbook first started, there was an unwritten rule that every topic area would include three examples: one for each built-in story format. For whatever the topic was, it would be covered in every story format. For about six months, this lasted as the rule. And then special cases started to develop.
Some problems are much harder to solve in one story format and others. Integrating anything using JavaScript, for example, is significantly harder in Harlowe than Snowman. And solutions that rely on macros and built-in functionality for styling code are far easier in SugarCube and Harlowe than Snowman. The idiosyncracies of each story format make it complicated to develop universal solutions. Some solutions, we finally decided, simply can’t exist in all story formats.
The same can be said of individual example credit. Looking back on the very first release of the Twine Cookbook, the original plan was that many different contributors would write their own versions of solutions which would be compiled together and linked by topic. This proved to be wildly ambitious and completely wrong. Some people have and continue to contribute code and feedback, but the vast majority of the users of Twine and the Cookbook have become what I call the “silent” community.
I have learned from talking to people both in person and through private online conversations that many people appreciate that the Cookbook exists, but they are often at a loss at what they could individually contribute. Educators especially, a group I claim as my own, often have suggestions for how their students might use the resource, but have to create their own specialized notes for their courses. They can give advice and feedback, but not code or work on the documentation itself.
In trying to decipher how best to work with this “silent” community, I have turned to existing resources: the Q&A, Twine Twitter account, and the Twine Discord server. I try to look through what people are discussing, problems they might be having, and what they ask about. I then make a list of topics that should be covered and try to determine what other topics are dependencies on them. For example, if people are discussing using an external library with Twine, I know that we need sets of examples on both using JavaScript and another set on using external resources and then to link them together.
Looking at what people are using means also shifting away from individual scenarios into examples that build upon each other. The original planning was that other developers would add code, but it turns out that the best changes came not from other authors, but those first learning Twine. By watching what people were struggling with, I was better able to adapt the Cookbook to that audience. Although talking with them would be the best way, I have not always been in a position to do that. Often, I work through what people ask about and how they discuss their issues, playing the role of an ethnographic researcher to my own group and community.