The Developer Documentation OEP PR landed Jan 14th. The community came together with reviews and comments, which culminated in this OEP resulting in a much better state than where it started. Now, 3 months later, let us reflect and review the impact and adoption of this OEP to date. We look forward to continuing to work with the community to adopt documentation best practices, reminding ourselves and our teammates of this OEP, reflecting back on the impact of these changes and updating this OEP as we go and learn from our experiences.
We appreciate your participation in our common goal of creating a more approachable and maintainable platform (codebase), resulting in sustainable improvements to developer velocity and usability of our features, eventually resulting in an open source platform that we are proud of.
Swagger - the DRF generated spec didn't really give us what we expect, and seemed hard to customize and keep such customizations up-to-date. Didn't support easy "tagging", I think. We ended up writing our spec manually. Zach Hancock knows more about this.
ADRs
Announcing ADRs when they are published
Where to announce to? All of edx-code? On slack somewhere? #dev?
Recommended durations for open discussion of ADRs
Since it's a local decision, can use the same process that already exists for the local repo.
Confluence
Have a regular time period for reminding folks to cleanup/archive Confluence pages - maybe at the beginning of each quarter
Maybe an automatic wiki gardener that flags unused/unreferenced pages for either archival or promotion?
READMEs
Writing README files in edx-platform
Discovery
Better discovery for documentation than knowing the person who created it.
Have a single documentation "portal" that points to everything - docs.edx.org or something
Read the Docs
Publish edx-platform code docs/docstrings to RTFD
Clean up old ReadTheDocs projects
Do ADRs and other documentation in github repos get ingested by readthedocs yet?
Have a place for "design system" / style guide documentation
Having a single source of truth
devstack doc in readthedocs AND the github repo, for instance
Wish item: Curated ADRs blog post that lists reverse chronological ADRs
ADRs are in Github repos. If they are in a standard location, then it should be straightforward to automate searching repos for new ADRs and post them
OEPS
Better communication around OEP status
Format
Better communication of tools like pandoc and cheatsheet.
Documenting micro-frontend best practices
Can be system-wide developer-docs
I guess actually using the developer-docs repo for words/pictures about software that crosses service boundaries?
Hire another tech writer. Our current one is old and used up.
"extensively validated in production"
Getting feedback from people that were more resistant to parts of the OEP.
Merge or otherwise close out the 5 OEP PRs open since 2018
Is the /docs folder supposed to generate something on Read the Docs? For all repos?
We may in the future.
Use ADRs as doc-substitutes (don't stop at ADRs, often need a HOWTO etc.)
Discourage use of markdown
acknowledge that people will use MD
Still a struggle to create github docs with same level of draftiness that feel ok in Confluence.
READMEs
Maintaining good repo-level READMEs - I like having that single point of reference for understanding how to plug into devstack, configuration options, testing, PII annotations, etc.
Personally ok with main READMEs including basic usage, even though OEP has this in how-to.
ADRs +3
Helps with preliminary design thinking and gathering alignment
ADRs are a good way capture decisions local to a repo