Add current ways of working to Seshat project readthedocs
Closed this issue · 8 comments
Pre-requisites
- Seshat-Global-History-Databank#23 so we can show RAs progress so far when consulting them on their respective pages
Docs pages
-
Could look similar to https://alan-turing-institute.github.io/trusted-research/Live at https://seshat-global-history-databank.github.io/seshat/index.html - Pages for processes for each role
- Seshat Admin
- GitHub workflow
- Database backup procedure
- Include a schema map of the db
- Setup documentation
- General notes on Django etc
- How to edit readthedocs
- Research Assistant (could we work with Matilda on some of these in advance of the workshop?)
- Link to example notebooks for using the Seshat API and Cliopatria GeoJSON
- Data cleaning methods: page with links to repos/notebooks with code that can be run to reproduce data extracts used for research projects/papers, with the latest data from the website
- Data analysis: links to notebooks/repos/scripts from research projects showing some analysis in Python/R
- How the Seshat comment system works generally (is this recorded anywhere already?)
- How to use the Seshat comment system to make requests of the Seshat Admin(s)
- How to make database edits
- How to make edits to Cliopatria #140
- How to edit readthedocs for RAs, which could be a simpler approach than described above for an admin familiar with Git, involving editing the page in GitHub (which should trigger a PR automatically for non-admins of the GH repo?)
- Seshat Expert
- How to use the Seshat comment system as a Seshat Expert (currently disabled)
- Public User (maybe don't need but could include some "how to use Seshat guides")
- How to suggest edits via the Seshat login system (this page should be linked to from "Seshat Expert" too)
- Institutions and people
- Who to contact for what, and who to contact when they're on leave. e.g. who at CSH should be contacted to restart VM if the site is down and Majid is on leave
- Need to determine the appropriate level of public facing info on contact details (or if this is only relevant for project members, write it down somewhere private and link to it)
- (Optional) A "Legacy Resources" page with links to any and all websites, wikis etc of the Seshat project
- Code of conduct
- Seshat Admin
TODO
- Consult with Seshat project people on how they are doing things currently for first draft of pages
- Create separate issues for specific docs pages above
- Do a first draft of all these pages
- Make it so that anyone in the project can update the readthedocs and can give others access (i.e. ensure all RAs have write access)
The people to get in touch with are:
| Person | Institute | Role | |
|---|---|---|---|
| Enrico Cioni | ecioni@turing.ac.uk | Turing | RA |
| Samantha Holder | samantha.louise.holder@gmail.com | Pieter: "works as a casual Research Assistant for us, so not formally attached, more a consultancy role" | RA |
| Jakob Zsa | jakob.zsa@gmail.com | CSH | RA |
| Jakob Hauser | jakob@hauser.earth | CSH | RA (NLP) |
| Jenny Reddish | reddish.jenny@gmail.com | CSH | RA who has worked on Cliopatria |
Pieter: "Once a draft has been created I think quite a few other eyes will have to go over it, e.g. myself, Peter, Dan, Jim …. . I am happy to lead on this editing process. "
thanks @edwardchalstrey1 !
@kallewesterling is documentation something you're interested to take the lead on? I've updated this issue to be clearer with what I intended: basically to get in touch with the current key user types and specific people on the project and write down their current processes in the docs, but also ensure there's a process by which they can edit (or at least suggest edits) going forward
Sure thing! Sounds like something that'd be typical RAM work, to be fair. I might just do some user interviews!
Sure thing! Sounds like something that'd be typical RAM work, to be fair. I might just do some user interviews!
Perfect, that sounds like what I had in mind 👍
Another quick thought: once the above is done and we have both a) a rough documentation of current processes and b) a rough plan of how the project should work going forward, in a sustainable manner, it might be worth inviting Pieter up to Turing for half a day to figure out a plan of action for how to improve/ implement the processes
One additional comment from our meeting with Majid is that we should document how the RAs currently use the comment system in Seshat to make requests directly to Majid.
@kallewesterling I've deleted some of my comments above and hopefully everything here is clear now - but feel free to reopen this on the new repo according to one the templates if that would help to structure it better
Closing as replaced by: