Arch Hour Documentation Ideation - 05-05-2021

On 05-05-2021 at Arch Hour we had a 20 minute ideation session on ways in which we could improve our developer documentation.

We started by thinking about other project documentation that we good experiences with:

  • Django, Python

    • A very useful subset of this for me has been the version indicators (“e.g. added in 2.2”)

    • Separation of howto-style broad overviews and detailed API docs.

  • React

    • Very clearly organized and easy to navigate

    • Has a good combination of examples, philosophy, reference, to support multiple learning styles, etc. 

  •  Qt

    • Release notes, API docs, howto guides, topic overviews

  •  New Relic

    • Generally found this to be a good experience.

    • Search in google, or in New Relic can help find docs or community threads with relevant data. 

We then moved on to ideas we have for the Open edX documentation. Majority of participants are labeled below:

  • Discovery

  • Doc UX.

    • Navigation. Get everything under one roof - for instance, can I actually navigate from the edx-toggles documentation back to the main developer docs site?

      • [Feanil] OMG Yes: +1000, our docs are not very well organized at all and there isn’t a good unifying top level that orients you.

      • [Robert] Agreed - good top-level would be useful, but there is also a question of getting from leaves back to top-level.

      • [Jeremy] Have a main TOC project that just links to all the various independent docs projects?

    • Flow. Many other projects start with an intro, then installation, then startup, etc., in a logical flow that a new engineer could follow.  From what I saw, ours started with links to all the other doc we have that you may want to go look at first, or if you had some other need, which was daunting. 

  • Authoring Efficiency.

    • Publish. We don’t currently publish the reference docs for edx-platform(pydoc) is this because we expect most people to use their IDEs to get at this information?  I’ve found having browsable/linkable reference docs to be really helpful when teaching and to explore a code base.

      • [Dave O]: My understanding is that it was just cumbersome to build and kept breaking, and nobody wanted to maintain it.

        • [Jeremy] It was tough for Read the Docs to actually install everything needed for the imports to parse correctly.  Might actually be easier if we built using our own Docker image or such

          • [Feanil] Maybe via github actions is also possible?

      • [Ned] Would we want to publish all docstrings, or only the ones for “public” use? AFAIK, we don’t have public ones identified.

      • [Ned] I suspect many of our docstrings would not publish well, or are wrong, or are mis-formatted. I would want to pair publishing them with an effort to make them useful.

    • Updates. I wonder if we can reduce the friction on adding to the doc - it seemed odd to me that it needs a build and test suite.

      • [Feanil] Make “Edit on Github” available on all of our docs. 

      • [Ned] The build and test suite helps find errors, for example, broken inter-page references.

  • API Docs. Are we able to use it for API doc from code?  

    • [DaveO] Having a simple path to documenting our own edx-platform internal APIs in an in-code way would be nice.