2022-03-16 Mitchell/Wagner Check-in meeting notes

Participants

  • @Jeffrey Wagner

  • @Josh Mitchell

Discussion topics

General updates

  • JW – We have an AWS billing account now, I don’t expect you’ll need it but let me know if that changes

    • JM – Only for compute? Or also hosting?

    • JW – Our current plan is just using it for unforseen compute emergencies. But in a few months we’ll have ongoing operational costs for storage of F@H outputs.

  • JW – Some org-wide way to answer "Can I do X?" "What software does it?" "When will it be ready for use?"

    • JW – Currently we have a technical dashboard that lists our software status: https://github.com/openforcefield/status/ , but I don’t think this would be suitable for “lookup” of the software for a specific need

    • JM – I’ve been thinking about this. There’s a fair amount of duplication in our docs (or places where there SHOULD be duplication), so a central place for these sort of docs would really be great. Or we could store each markdown docs in its most relevant project repo and import those into a central location.

    • JW – We could have an “asparagus” model for inter-package docs, where some pacakges are more “central” than others, and inter-package docs would always go in the more “central” one. This would ensure that, if we ever run out of resources and have to scale back, the inter package docs would survive/remain tested and have developer attention.

      • JM – This would result in all the docs being in the OpenFF toolkit

      • JW – That’s true

    • JM – There are two ways to look at this -

      • Developer-centric is kinda what we’re doing now, where each package has its own docs, and the commonalities between them are from developers inviting me to come fix something, and me bringing a shared understanding of the other packages into their docs with me.

      • User-centric would be to have a single place for the docs where everything is worded consistently and we can control how concepts (eg “OpenFF Molecule”) are introduced. This would provide a better user experience.

    • JW – We seem to have two goals that are directly at odds -

      • “Projects are easy to deprecate and don’t break other things if they go unmaintained/disappear

      • “Projects share explanations of key concepts in a way that is straightforward for users to follow”

    • JM – One extreme is “every project references every other project”, which is kinda a worst-of-all-worlds (it’s very brittle and there’s a lot of repetition/confusion about order). The opposite extreme in the “brittle axis” is the “asparagus model”, where inner packages can’t reference outer ones. One way to avoid excessive brittleness and have little confusion would be to have central docs.

    • (General) – Could do “ladder docs”, where we have a paragraph for each package. Each package could maintain its own paragraph

    • JM – What about a case where the user guides could be concatenated into a comprehensive “openff book”?

    • Decision - In the future, packages that don’t have pre-existing user guides should have their user guide become part of the OFF Toolkit’s docs. This prevents repetition of core concepts, improves searchability, and makes for clearer explanations. Packages that have their own user guide will be imported in the OFF Toolkit’s docs (at least their section headers, which can link out to original docs)

  • JM – I’m thinking about trying a new doc rendering method - mdbook. I may do some of my next PRs in it.

    • JW – That sounds cool. Please let me know that it’s somewhat mainstream (like, it’s used in other big packages) or that there’s an easy fallback if it breaks.

Todos

  1. (high) QCSubmit users guide (in progress)

  2. (high) Bespokefit theory docs

  3. (high) Interchange pre-release prep

  4. (medium) Toolkit docs cleanup

  5. (medium) Toolkit revised user guide (+-unifying/centralizing package user guides)

  6. (medium) Come up with “milestones” for making first of three videos this year (like, “first video on covid spike protein and small molecule, filmed this day, edited in that range, etc…”)

  7. (low) “How to cite” section on website

  8. (low) Propose policy for using GH citation machinery

  9. (low) Check main website for broken links

  10. (low) migrate docs to be under http://openforcefield.org domain (openforcefield/status would be base project repo)

  11. (low) Conda env yamls for each release (automated inside of Toolkit’s single-file-installer action)

 

Action items





Action items

Decisions