A collaborative guidebook for informatics playbook
The live version is rendered at:
Any new commit push to this repo will trigger a rebuild, so you will see the latest changes from the above URL.
Each chapter should have the following sections:
Section | Description |
---|---|
Intended audience | The chapters will cover heterogeous and not necessarily overlapping target audiences; therefore please include a short description to ensure readers' time is wisely spent. |
Current version / status | Guidance tbd, but some indication of whether the draft is early, actively soliciting comments, or ready to implement |
Lessons learned / summary | This section is optional but encouraged in chapters where the source of truth for the majority of the content is external (Incorporated here by reference only) |
Why this is important | Description of the problem and vision for what best practices will address or make possible |
Status and feedback mechanisms | What stage is it in the development process? (See options below). Description and links for how people can comment, or contribute -- whether via Google form or GitHub issue etc. |
Takeaway List | A bulleted list of things you can read and implement (similar to top 10 PLoS Top 10 articles). |
Deep dive into takeaways | Each item should include specific examples that demonstrate that practice XYZ is possible and offer some insight and evidence as to why doing it one way (vs. another) is better. |
Acknowledgements | Key sources and or contributors. Note that references are most easily incorporated as hyperlinks rather than footnotes. This also makes it easier to read. |
Chapter status | What is in it | What the stage means |
---|---|---|
Stub | Outline with importance and audience specified | Open for high-level comments |
Early draft | Outline and preliminary content | Open for community contributions |
Ready for comment | Mature draft | Actively soliciting more in-depth community feedback |
Implementation-ready | Mature draft revised in light of input | Ready to be implemented, and evolved according to real world experince with it |
main.py
allows you to convert a google document to a markdown file and add it to chapters. To use this run python main.py <your_google_document_url>
. The images will be downloaded to docs/_static
and the document will be added to docs/chapters
.
credentials.json
for the google doc apis to work. This has to be at the root folder of the project. See here how to get the credentials.json
https://developers.google.com/docs/api/quickstart/js..md
extension under docs/chapters. Typically you can name it as chapter_[number]_[brief name].md
.