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 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: GitHub - openforcefield/status: Assorted maintenance tools within the Open Force Field software stack , 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 – 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 - 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.
|