Arch Hour Documentation Ideation - 05-05-2021
- David Joy (Deactivated)
- Ned Batchelder (Deactivated)
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
Search. Enhance the little-known docs search page (and search results) Maybe we should just prominently mention it on http://docs.edx.org so people find and start using it?
Multiple Locations. [Robert] Confluence vs Repos is still a personal question for some types of docs.
[David Joy] Seems like it’s confluence vs. doc site vs. repos to me… even worse. A way to link documentation in repos to the docs site might help, but might also make things feel weirdly inconsistent.
[Robert] Recent Confluence page edit led me to ask if the page should move to a repo, and Ed mentioned that it shouldn’t move if it would increase doc-writing friction. I agree - sometimes.
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.
frontend-platform has been able to do this… its doc site uses jsdoc and Markdown and is generated from the code with one command. It’s very convenient. (It’s not perfect, of course)
[Feanil] Do you mean like Open edX API or something else?