Moving the documentation to community-contributable system?

George

Hi Josh! I was wondering if you had considered moving the Bpod wiki onto something more open-sourcey and sleeker. I think the formatting options for the google site are pretty limited, and the docs would benefit from user-contributed updates. readthedocs.io is an obvious choice, but maybe it's a little over-kill. I recently found a short demo of Asciidoc, which Github renders well natively, so I thought this could be a simple way to host the docs. It opens up the option of using something like readthedocs or AsciiDoctor in the future too.

The format of the documentation repository might look something like this:

readme.asc
docs/
    general-concepts/
    protocol-development/
    assembling-bpod.asc
    bench-testing-bpod.asc

Just a thought since I've been getting new members of the lab onto Bpod and sometimes the current documentation feels a bit clunky. I'm willing to contribute.

George

I got a bit carried away and did a little of the work to see how it looks/feels. Check out this Github repo to see how the wiki might perform if it was hosted using just Github and Markdown.

Everything's in Github flavoured Markdown so it's very easy to manage and contribute to, with just a small touch of html to get images aligned in the centre and in the right size. Code fences, embedded diagrams, and alerts/callout boxes add a lot to the ease of reading. I think the wiki is due for some polish and Github flavoured Markdown can do the job. I think navigation-wise the table of contents in the landing readme.md works pretty well, with the only con being that it's not persistent across the site like a sidebar.

I've changed up the organisation for the module documentation, putting the class and serial interface documentation for them in the same place, as seen in the rotary encoder example doc.

So let me know if this is something I might continue with or if I should shelve it.

Josh

Wow George, that's a cool concept! Thanks for setting up the look & feel preview!
Bpod's documentation would definitely benefit from version control and some way of supporting curated user contributions.

I'm also in favor of a more future-proof host (e.g. github). Last year Google sites forced an update to their new version of the product. Their auto-migration tool made a huge mess of the Bpod and Pulse Pal wikis, and it took a few days of manual editing to fix it. There's no saying when they'll do something similar, or discontinue Google sites entirely.

I'm admittedly not familiar with markdown (github flavor or otherwise). It looks like there's a small learning curve to traverse, which shouldn't be much of a problem for us at Sanworks.

Unfortunately I won't personally be able to contribute to this for a while. With our small R&D team, we're working at full capacity to overhaul Bpod's Python software, with an anticipated release at year-end. Bpod's dependence on MATLAB is a major bottleneck for adoption of our platform beyond our current user base, and complicates integration with emerging software tools. Once we have working Python software, documentation and tutorials will be at the top of the stack.

I'm definitely interested in a documentation scheme like what you've put together in the long run, so the verdict is don't shelve it! If you have bandwidth to contribute more, I'd be more than glad! I'd also be glad to meet sometime if you'd like, to talk through some ideas. Let's follow up by Email - support@sanworks.io

Thanks!

-Josh

Josh

The Bpod Wiki is now fully migrated to Github:
https://sanworks.github.io/Bpod_Wiki/

Major thanks to George for this incredible contribution to Bpod!!