Organized Chaos
As we set out to create the Maker Event Playbook, we realized that unstructured documents or a wiki was likely to become disorganized and abandoned in a short time (as we’ve seen numerous times before). Simply managing permissions on a Google Doc (or a folder of Google Docs) or a wiki can be a full time job when you have hundreds of likely contributors. As we worked to find a solution, we realized that there is an existing solution to this problem - in the form of Open Source Software development.
Open Source Software development
Let’s learn more about Open Source Software development, and why this proven model can be used for the Maker Event Playbook.
1. What is Open Source?
“Generally, open source refers to a computer program in which the source code is available to the general public for use or modification from its original design. Open-source code is meant to be a collaborative effort, where programmers improve upon the source code and share the changes within the community. Code is released under the terms of a software license. Depending on the license terms, others may then download, modify, and publish their version (fork) back to the community.” Wikipedia, Open-Source Model
2. How does this apply to a playbook / documentation?
Open source software sets out to collaboratively create source code, and we are collaboratively creating documentation. Documentation is similar to source code in that it is written in an editor, it has conventions that guide its creation, and it goes through many revisions in its lifetime. The tools that help Open Source software developers manage and publish their code can be leveraged for documentation, and this happens as a natural part of most Open Source software projects - the software developers write and host their documentation alongside their code using the same tools.
3. What are the Open Source principles?
As a core project team, we hope to build a community of contributors for the Maker Event Playbook. We can continue to look to the Open Source software model to guide our project by using the Open Source Principles.
Principles as published in “The open source way” at opensource.com
-
Transparency. Whether we’re developing software or solving a business problem, we all have access to the information and materials necessary for doing our best work. And when these materials are accessible, we can build upon each other’s ideas and discoveries. We can make more effective decisions and understand how decisions affect us.
-
Collaboration. When we’re free to participate, we can enhance each other’s work in unanticipated ways. When we can modify what others have shared, we unlock new possibilities. By initiating new projects together, we can solve problems that no one can solve alone. And when we implement open standards, we enable others to contribute in the future.
-
Release early and often. Rapid prototypes can lead to rapid discoveries. An iterative approach leads to better solutions faster. When you’re free to experiment, you can look at problems in new ways and seek answers in new places. You can learn by doing.
-
Meritocracy. Good ideas can come from anywhere, and the best ideas should win. Only by including diverse perspectives in our conversations can we be certain we’ve identified the best ideas, and decision-makers continually seek those perspectives. We may not operate by consensus, but successful work determines which projects gather support and effort from the community.
-
Community. Communities form when different people unite around a common purpose. Shared values guide decision making, and community goals supersede individual interests and agendas.
4. Open Source Software development tools
We’ve made you read this far, and still haven’t explained why we chose GitHub, so let’s get to it :)
GitHub offers a number of features for Software development - and if we treat our documentation as a form of software, we can take advantage of the same features.
1. Open code repository with version control
We need a safe place to store all our playbook files, and we need to track changes. A GitHub “repository” stores all the files in a folder structure and all changes are tracked (and can be undone!)
2. GitHub Pages
GitHub has a built-in way to share documentation as web pages called “GitHub Pages”. If you create your documentation in a specific way, GitHub will automatically update the web pages as you change the documentation.
3. Tracking of issues
GitHub tracks “issues” which can be assigned to specific contributors, tagged with extra information, and statused as work progresses to resolve the “issue”. While “issue” may sound bad, these are really tasks which can be created to track a new item, or to track a problem that must be resolved.
4. Review of contributions
GitHub has a structured way for contributors to submit potential changes to files. Because we are working in the open, anyone can check out the repository and then propose changes. These changes are then reviewed by a group of maintainers for the repository. This group can comment, propose changes, and give feedback right in the tool. Once changes are accepted they become part of the repository. This feature set is very powerful, and even contains tools that resolve merge issues when two contributors make changes to the same file at the same time.
5. Notifications of changes, comments & more
With a large, diverse community of contributors, it can be hard to stay informed. With GitHub, you can subscribe to notifications for the entire repository or just specific parts of the repository so that you can stay up to date.
6. Forking
We want major maker events (or even smaller ones!) to be able to create a copy of the playbook that is then tailored to become the documentation for that event. GitHub supports this with the concept of a “fork” (think “fork in the road”) where you can create a new repository based off an existing repository. We HOPE that your event will fork the playbook and then fully document your event!
7. Scalability
GitHub is the repository for many large Open Source software projects and capable of handling any documentation we can create and any number of contributors.
8. A LOT more.
Just ask your favorite software developer (make sure you have some time). As the project and the community grows, we expect to leverage more and more of the GitHub toolset.
5. Getting Involved
Now that you know why we chose to develop the Maker Event Playbook using Open Source principles and tools, you can learn how to contribute to the playbook!