Open docs strengthen the Bpod platorm
The case for open source scientific instrumentation is straightforward, but advocates tend to focus on its transparency, flexibility and low cost. An underappreciated merit is that occasionally, members of the user community surface with a major project contribution.
In a recent forum post, community member George Stuyt took it upon himself to migrate Bpod's wiki from its original home on Google Docs to a vastly more flexible and open format. The new site is encoded in markdown, hosted in a public Github repository, and served as a live website using MKDocs.
Here are some advantages of the new setup:
- Predictable hosting. In January 2023, Google forced migration from its classic Sites product. Migrating the Wiki to new Sites required days of manual editing, and similar policy changes could be made at any time in the future. Encoding the Wiki in Markdown for MKDocs gives us the option to take over hosting from Github if necessary.
- Credit assignment. Community members wishing to add corrections or new content to the Bpod wiki can now fork the repository, make edits, and submit a pull request. They will then be automatically attributed as the content's contributor in the Wiki's commit history, and in the 'Contributors' section on the repository home page.
- Version control. Since the live website is served from a repository, the Wiki content can be versioned and changes can be easily reverted if necessary.
- Standard format. Markdown is quickly becoming an industry standard documentation format, especially in the open source community with the advent of Github-flavored Markdown.
- Modern aesthetics. Open doc tools like MKDocs and Sphinx ease the user's experience in the bland world of technical documentation by giving the content a clean layout with a modern look and feel, while requiring little work on the part of the content creators.
We hope you find the new Bpod wiki to be even more useful and informative than its predecessor. Major thanks from all of us to George Stuyt (currently in Palmer Lab at University of Melbourne) for the new wiki's conception, migration and provision of additional content! Comments and suggestions are more than welcome at: admin@sanworks.io
