Skip to main content

Documentation Guide

See also

High Level Patterns

Page naming and organization

  • Title of page must convey what the content of the page is without being overly long
    • if needed, use a subtitle to clarify who the audience
  • Try to separate pages by content type (inspired by the diataxis approach to documentation)
    • overview/marketing - high level 'teaser' page that illustrate at a glance what this is, why you'd want it.
    • reference material
    • how-to guides
    • tutorials. We don't have many of these... yet
      • explanation - deeper explanation reasons behind things
  • How-tos should use active voice.
    • How to create a riverscapes project ✅
    • not Creating a riverscapes project ❌
    • not Riverscapes projects ❌
  • Every page title within a section should ideally be unique to avoid confusion in search results or browser tabs.
  • Page titles can repeat information from their parent, but paths should not. For example a page may be titled "Data Exchange API Reference", while its url is data-exchange/api/reference. The title is not "Reference" and not the url is not data-exchange/api/data-exchange-api-reference.

Paths

  • lower-case and kebab-case, ie data-exchange
  • Favour flatter hierarchies over highly nested paths - 4 levels should be the maximum
  • nav path can introduce organization that is not part of the URL. In example below, the page who-can-apply is nested under Introduction but "Introduction" is not part of the URL path algolia screenshot
  • thus all our major 'products' are top level paths, e.g. data-exchange, viewer, riverscapes-projects

Images

Images should be stored in folder static\img\. If specific to a certain page, put it in a subfolder corresponding to the section.

Outside Examples

Since we are using Docusaurus, looking at other sites that also use this tool is especially useful.