Handbook Hackathon December 19/20th CET

[adswa]

General overview

There will be a hackathon concerned with the DataLad Handbook on Monday, Dec 19th, and Tuesday, Dec 20th - its rather spontaneous, but it makes sense to use the current momentum and see how far we get.

The Hackathon is part of our Labs regular hacking time slots, but anyone reading this issue is welcome to join the effort, at any time, for any duration. We will hang out at https://meet.jit.si/PsyinfCoWorking, approximately during central European office hours.
We will kick off the hackathon on Monday, Dec 19th at 9AM UTC+1. I'll give an overview of how the handbook works, but this can also be read up upon in http://handbook.datalad.org/en/latest/contributing.html.

Goals

The overarching aim is to get everyone who's interested familiar with the way the handbook is build such that the entire project becomes more resilient on the social level. A certain end-of-hackathon aim is to do a long overdue release. On the topic of possible concrete work packages, I'm proposing several independent handbook aims we can work on in parallel, if they draw in sufficient interest.
I'll write them up as dedicated issues, and link them here

1. Turn the handbook into a testing framework

This is certainly the most attractive project from the perspective of datalad core. Skills relating to CI (Appyveyor/GH), Sphinx, integration testing, scripting, ... will come in handy

• Actual workflow testing #631

2. Lower technical barriers to contributions

This is a nice-to-have, and benefits from skills relating to CI and Sphinx

• Add support for non-local builds #886
• Compartmentalize the Makefile  #894

3. Add concrete contents

There is a long list of feature requests related to write-ups of functionality that isn't yet in the handbook. Anyone can contribute by writing about their topic of choice. Some have made it into issues already:

• Create yet missing big usecases #857
• Document add-archives-content example #811
• Needed: Section on credential management #760
• recommended practice to keep your dataset "lean" #619
• Workflows with Datalad #617
• Needed: A section on working in shared repositories/datasets #575
• A section on collaboration on HPC #524
• New Advanced chapter on Extensions #883
• Add a section on built-in datalad git-annex special remotes (datalad, datalad-archives) #748
• "Principles" section for git/git-annex internals #654
• Addition to "file system operations" or "help" section on accidentally modifying annexed files #543
• Section describing on how to establish "pull requests" for git-annex'ed repos on github et al #674
• already in progress, waiting for coauthors to join in: Add a draft for annex encryption usecase #895
  But there is also expertise in our group that could be distilled into new use cases and chapters, e.g., archival workflows, the SFB in Cologne, ... . If some topic tingles anyone's creative juices, please feel free to start - even only a first rough draft is highly appreciated. http://handbook.datalad.org/en/latest/contributing.html#desired-structure-of-the-book contains info to gauge where in the book a new contribution could be added (feel free to create new chapters in the appropriate part of the book if you feel like it makes sense)

4. Miscellaneous "easy" or small issues

If someone is looking for small things to do that don't take much time until a PR, these issues would be worthwhile to look at:

• add :numref: to figures , check for hard-coded figure references, and replace them: Replace hardcoded reference(s) to figure numbers #824
• add alt text properties to images: Add :alt: properties to all .. image:: directives #681
• Any Windows user can help with A Windows rendering of the handbook  #632. Either by testing the existing Windows Wits, or by adding new Windows Wit where they are yet missing. Brainstorming how to best create a maintainable Windows rendering of the book are also appreciated.
• Typos, grammar, and consistency. If someone is up for letting a spellchecker loose, or feels like having a cozy reading hour, any issue or fix relating to "does the writing work" is appreciated
• [BUG] handbook renders page titles strangely #884
• Bump "minimal supported DataLad version" and adjust contents #888

5. Cut contents

The handbook is a substantial wall of text, and in the past it has only grown. I'm certain that there are some sections that could go away, e.g., because the feature they're describing isn't that relevant anymore, or because their outdated, or because they're superfluous. Suggestions welcome!

6. Analytics

• Make use of readthedocs analytics #889

7. Cheat-sheet

• Check if the cheat sheet is still up-to-date, and if not, extend or enhance it: https://github.com/datalad-handbook/artwork/blob/master/src/datalad-cheatsheet_p1.svg

8. Art

• Create a handbook sticker (in svg format) that we can produce and gift to contributors

[adswa]

How to best prepare:

• Let me know if you need access
  • to this repo
  • to the readthedocs project
  • to any other repo in the datalad-handbook organization
• Let me know if the kickoff time doesn't work. We can reschedule if the time is inconvenient to many
• Scan the handbook's table of contents for a rough idea of the content, and also the issues in this repo for anything that catches your interest

[mih]

Log: https://github.com/mih/autorunrecord has a README with meaningful documentation now

[adswa]

closing this overview issue, as the last PR from the hackathon has been merged.