This Guide Book aims to provide help for contributors by offering advice and best practices that they can use during their work. It also aims to guide decisions and operations of the Docs Working Group as a whole.
- Prefer plain language
- Improves accessibility to a wide range of people with different backgrounds
- Where jargon is used, define it in-document or link out to a glossary or other source
- Use deep page heirarchies
- They provide detail without overwhelming readers (with length and complexity)
- Think Wikipedia page structure
- Break up long documents into separate parts where feasible, and structure complex information into separate, focused topics where feasible
- Prefer interlinking between pages within a subproject or topic, and to other projects
- The Project Jupyter (meta) docs pages are a great target for interlinking because they are relevant to many subprojects
- Breaking up a topic into small focused documents and interlinking them can provide the same information in an easier to read form
- Consider how your content fits into the diataxis docs framework before you start, to ensure your content is focused toward the right purpose
- Key Docs pages should be checked before release, so that essential information is not broken
These points were brought up during early Docs Working Group discussions. Some common challenges we need to be aware of while doing our work:
- Users often express that it's challenging to get a unified view of "what is Jupyter" and how the components work together.
- We should work to remedy this and provide more explanation and context in appropriate places.
- Jupyter's modular approach (from The Big Split) can make it difficult to communicate the right information in the right place. Insights from one project can be relevant to other subprojects, and some information spans multiple subprojects.
- There should be multiple ways to consume docs, through multiple points of delivery.