Suggestions for improving the OpenSafely documentation

The following are some suggestions for content that could be added to the OpenSafely documentation from the perspective of a new researcher. Feel free to disregard the suggestions if you feel that they would not be useful or would be difficult to implement. I would also be happy to try implementing any suggestions that would indeed be helpful.

Content

• An ehrQL cheat sheet could provide users a quick view of the most common syntax rather than having to read long, text-heavy tutorials/references.
• Exercises could enable more active learning of ehrQL, since programming tends to be more easily learned through activity rather than reading. This could be used in the future in the development of some sort of self-learning course. These could be simple, multiple-choice Qs to test understanding, or more extended coding tasks.
• A section for 'coming from Python/R/SQL' could help users familiarize themselves with ehrQL more quickly by learning the similarities/differences of ehrQL and their own language, since many users know one of these languages and ehrQL has similarities with Python (classes, methods), R (libraries, functions), and SQL (schemas, queries). Having a link on the homepage might be useful for new researchers.
• Testing ehrQL queries is currently in the how-to-guides in the ehrQL section. It may also be considered best practice for using OpenSafely, so an incoming link from that section could be helpful.
• A complete tutorial from start to finish could help in clarifying what a complete analysis pipeline looks like (at a lower level than seen in the 'analysis workflow section').

Navigation

• The homepage has a lot of text, which makes it difficult to quickly find useful links and sections. Using a more abstracted/simplified homepage section could enable faster navigation to important sections/links. This page could then have a link to an about/introduction page for people who are unfamiliar with OpenSafely (equivalent to the current homepage).
  • Navigation is already available via the sidebar; however, a navigation-oriented home page may still be useful because:
    • The first thing people will look at is the actual content of the homepage, rather than the sidebar. This may particularly help new researchers less familiar with the structure of the documentation.
    • Images can be used to make recognition of desired sections faster, which is not possible with the sidebar.
    • The sidebar automatically hides when the homepage is opened in a smaller window (e.g. split screen). Personally, this meant I did not see the ehrQL reference for a while.

Start by reviewing the documentation homepage, the ehrQL tutorials and reference, the testing how-to guides, and the analysis workflow section. Compare the proposed cheat sheet, exercises, language guide, complete tutorial, and navigation changes with the current structure. Done requires agreeing on a narrower, actionable scope and identifying the documentation pages to update.