New in-CMS user help documentation module

[GuySartorelli]

We have decided to implement a module that provides user-help documentation within the CMS. This will allow users to access help documentation that is version controlled to the specific versions of each module they install, as well as integrating project-specific documentation within the same docs.

One of the main tenets guiding our decisions here is that we want to keep thing simple. Extensibility and flexibility is good, but making sure that writing docs and maintaining the feature set isn't a pain is very important here.

Main features

• A link is added to the left-hand menu which leads to a new user docs section
• User docs section includes a search feature
• User docs section includes a tree navigation.
  • The docs can have multiple trees, e.g. "global features", "pages", "blocks", etc (see design)
  • Tree roots do not necessarily link to a docs page, but every item under the root does
  • Where pages fit in the navigation is based on the folder structure (e.g. all files in the folder structure 00_global_features/00_navigation/00_level1 any module will all appear in that same section)
• Documentation only appears for functionality that exists in that project (i.e. documentation is bundled with the modules that provide the documented functionality)
  • For example a project that excludes silvertripe/cms doesn't have docs about pages
  • For example a project that excludes silverstripe/siteconfig doesn't have docs about the settings section
  • For example a project that excludes silverstripe/asset-admin doesn't have docs about the asset gallery
• Documentation pages include breadcrumbs which match the main tree navigation path to that page
• Documentation pages indicate whether they are from commercially supported modules, are project-specific, or are from third-party modules.
  • If feasible, when documentation is overridden, the overridden page can include multiple tags (e.g. "commercially supported module" and "project-specific"). This could be implemented using frontmatter metadata.
    • alternatively an "overridden" tag could be added for docs that originate from a module but get overridden in the project.
• Documentation pages can be overridden
  • For example, a page about the siteconfig (settings section) could be overridden by a project that has extensively customised the siteconfig
  • This is defined by having a page with the same name in the same folder structure (similar to how overriding templates works)
• Documentation pages can be extended. Extended content gets added to the bottom of the page.
  • Probably defined by frontmatter on a page with the same name in the same folder structure

In-context-specific functionality

• In edit forms in the CMS, a button is provided in the top right to access documentation relevant to that form
• Clicking the button results in the relevant documentation page sweeping in from the right
• The documentation panel can be dismissed with a close button
• The documentation panel doesn't have breadcrumbs but can contain links to other related documentation
• If the form is for editing a specific record (e.g. editing a page in CMSMain), the documentation in the panel is specific to the class of the record being edited
  • This falls back to parent classes if there's no documentation for the current class. e.g. NewsLandingPage falls back to LandingPage falls back to Page falls back to SiteTree.
  • Documentation doesn't have to be specific to that class - rather, we can map a class to a specific page of documentation. For example LandingPage might have documentation very specific to that page type - but SiteTree might just be generic documentation about pages.
  • If no relevant documentation is available, no button should be presented.
• If the form is not for editing a specific record (e.g. /admin/pages before editing a page), the documentation in the panel is specific to the class of the admin section the form belongs to (OR that's used as a fallback, and the modelClass of the given admin section is used initially)
  • The same fallback rules apply here, i.e. check for docs for the parent classes, and don't present a button if there's no relevant documentation.
  • This might be infrequent enough to not bother with - e.g. the /admin/pages example could be covered in SiteTree docs. Most (if not all) other admin sections deal with specific classes (e.g. ModelAdmin is whatever managed_model is active, settings is SiteConfig, etc)
• If the form is for something more generic (e.g. see the "Arbitrary Data Gridfield" in a kitchen sink installation), no documentation is provided.
  • We can always add a way to provide documentation for these random things later on as an enhancement.
• For inline-editable elemental blocks, the help button is available inside the elemental block after expanding it.
• For the asset admin and campaign admin, the help button is presented in the top right, next to the search button

Other requirements

• Follow the designs including at different breakpoints
• Appropriate accessibility guidelines are followed
  • e.g. good keyboard support
    • escape button closes in-context documentation panel
    • roving tab-index for the navigation tree
    • etc
  • e.g. good screen reader support
• Documentation is written in markdown
  • GitHub flavour syntax is supported (e.g. > [!IMPORTANT] blocks)
  • Images are supported, both hosted with the docs and via URL
• The functionality is provided in a new optional module
• The new module is included in silverstripe/recipe-cms
• The new module is included in the supported modules list
• Documentation is bundled with the modules that provide the functionality being documented
  • This ensures both that only relevant documentation is provided, and that the documentation is the correct version
• The documentation for supported modules is also presented on userhelp.silverstripe.org
  • The menu on userhelp.silverstripe.org has the same layout as the menu in the CMS when kitchen sink is installed
  • At the top of each page in userhelp.silverstripe.org there's some indication of which module the documentation pertains to
• Special rendering features that work in userhelp.silverstripe.org also work in the in-CMS rendered docs
  • for any of those features we don't want to support, we need to either remove that functionality from userhelp.silverstripe.org or lint our docs to prevent the syntax sneaking in.
  • We have decided we don't want [CHILDREN] syntax or API link syntax working in our user help docs.

Not doing

• No explicit domain-specific language to allow extensions at arbitrary points in a documentation page
• No ability to toggle documentation for specific features on/off based on YAML configuration
  • Instead, documentation should be written in a way that makes it clear when features might only be available for some projects, based on developer configuration.

Designs

• as a whole with side menu
• in-context for a page

Some similar concepts

• https://github.com/silverstripe/silverstripe-docsviewer (e.g. with https://github.com/swipestripe/silverstripe-swipestripe-docs)
• https://github.com/webbuilders-group/silverstripe-cmsuserdocs
• https://github.com/vulcandigital/silverstripe-userdocs
• https://github.com/somardigital/silverstripe-user-guide
• https://github.com/andrewandante/silverstripe-clippy
• https://github.com/unclecheese/silverstripe-docstation

[GuySartorelli]

I'm not sure if there's a sensible way to split this up into separate cards, beyond "do the big docs section", "do the in-context bit", and "update userhelp.silverstripe.org"

We'll also need to work with mock docs for a while until the new docs are written.

[emteknetnz]

A few things to add to requirements

• Can render images added to the projects github repository or hosted externally
• Follows design at different breakpoints i.e. the "Contents" is hidden behind a button on tablet and mobile rather than showing by default on desktop
• Core user docs match the version of modules installed i.e. we don't get CMS 6 docs for CMS 7. This should also work at the minor level to i.e. do not document CMS 7.3 features if the site is only on CMS 7.1
• Documentation is developer managed i.e. via the project github repository, not via CMS user editing or file manager uploads
• Pressing Esc on desktop will close the documentation panel if it's open

The documentation for supported modules is also presented on userhelp.silverstripe.org
Special rendering features that work in userhelp.silverstripe.org also work in the in-CMS rendered docs

We probably don't want to support some of the weird DSL's from the docs site, namely [CHILDREN] as that thing is a nightmare to work with. If we're aiming to keep the in user help and userhelps.silverstripe.org content 'in sync' I'd be very inclined to update how the docs sites does that 'in page navigation' (probably just rid of [CHILDREN] entirely and always show the nav)

[GuySartorelli]

Have updated the acceptance criteria, including the above points from steve as well as updating existing points based on an in-person discussion.

[GuySartorelli]

Something we forgot to consider is localisation.
My proposal is that docs are simply namespaced by locale. e.g. for silverstripe/cms we might have a base dir for user docs at docs/user/, and then localisations could be done like so:

• vendor/silverstripe/cms/docs/user/en/.../*.md
• vendor/silverstripe/cms/docs/user/de/.../*.md

For now just setting up the correct folder structure and making sure it will bring in localised docs if there are any will be sufficient, and the short-to-medium term plan will be that we only provide English documentation, but we provide the logic for projects to add translated documentation if they want to.

It's definitely not feasible right now for us to store localised documentation in supported modules, because we don't have multilingual experts on the team and that would make it nigh impossible to update. But I think it is sensible to provide the option for those who want to have localised documentation with the caveat that they have to provide the localisations themselves.