2019-04-08 Retro on Developer Docs OEP Adoption and Recommendations

Owned by Nimisha Asthagiri (Deactivated)
Last updated: Feb 08, 2021
3 min read

Date
ParticipantsNimisha Asthagiri (Deactivated), Adam Butterworth (Deactivated), Albemarle (Deactivated), Grant Goodman (Deactivated), Adam Butterworth (Deactivated), Robert Raposa, Alexander Dusenbery, Ned Batchelder (Deactivated), David Joy (Deactivated), John Baldwin, Dave Ormsbee, John Mark Walker (Deactivated), Calen Pennington (Deactivated)

Background

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.

Retrospective

Please enter your thoughts on what benefits we are already seeing from Dev Docs and should continue to do (Keep doing), what you'd like to see us (Start doing) going forward, and what you propose we discontinue (Stop doing). 

Start doingStop doingKeep doing
  • APIs
    • 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
    • Confluence
      • Archiving Confluence Pages
    •  Formatting
      • Auto-wrap seems to be working fine. 
      • Pandoc has made it very easy to convert to rST.
    •  

Notes

  • How-Tos
    • READMEs can contain intro-level how-to information + repo-specific short-how-tos
    • The how_tos directory can contain more detailed recipes
    • System-wide (non repo-specific) how-tos can go into https://github.com/edx/edx-developer-docs
    • Do we need a How-to for Dev Docs?  Folks don't know about the dev-docs repo and the pandoc conversion tool.

Action items