Co-authoring platforms about the-turing-way

[KirstieJane]

The BIDS community have just moved from google docs to building their standards on github: https://github.com/bids-standard/bids-specification.

There's quite a lot of linting and cleverness built in to their work flow - and I think it ends up on a read the docs site: https://bids-specification.readthedocs.io/en/latest. There was a big discussion about tools here: bids-standard/bids-specification#18.

I think the question about converting to a more traditional format is super useful - I'd be interested in brainstorming a way to actually turn this into a book at somepoint so it might be worth thinking of that for a long run consideration.

Thank you for opening up the discussion @pherterich ✨

[pherterich]

That's a super helpful discussion and trying to find something that can easily export to PDF seems to be really good, so I guess https://www.mkdocs.org/ should go on the list.
I guess there's always the option to turn some parts into PDFs and create a community on zenodo where all the PDF versions are collected and versioned?

[alexmorley]

My two cents: I think for authoring and collaborating on github (which IIUC is mostly the plan?) then using something built around that tends to work quite well. So my vote would be split between these two:

gitbooks Well established, full featured, good reading experience.
mdBook Slightly-less established and missing first class pdf export but has a really nice/clean reading experience.

[pherterich]

Just adding this here, not tools related but I don't know where else to put at the moment. Would we want to have a book sprint at some point? https://blogs.tib.eu/wp/tib/2018/11/13/how-to-book-sprint-in-sixteen-steps/

[r-j-arnold]

Just a thought about the presentation of the final product: I think the best practise sections should have a different background colour/be in boxes so someone who already knows about the "how" of a chapter (especially for technical chapters like the version control one) but wants to know more about best practise can find it easily. Also given the thrust of this project is good practise I think really highlighting those sections is merited.

[rosiehigman]

I'm on a call about a different project and someone mentioned this platform which might be an option: https://www.fiduswriter.org/

[pherterich]

Closing this as we went with JupyterBooks in the end. If we need standalone PDFs or something, we can cover that in a fresh issue.