Project-specific CMS user guides

56 views
Skip to first unread message

Jonathon Menz

unread,
Dec 7, 2015, 5:59:13 PM12/7/15
to SilverStripe Core Development
It sounds like there's already been some thought on this but just creating a thread here to continue discussion.

Currently the external CMS user help has a few problems for real-life projects:
  1. Missing help: No documentation of custom / site-specific functionality
  2. Redundant help: Modules such as Blog and Subsites are documented even if not installed
  3. Superseded help: When modules replace functionality (like KickAssets) the standard documentation doesn't apply anymore
A better approach may be to generate and display user help internally for each project.

The main user help guides could be stored in and pulled from the CMS module as a base, and these could be merged with user guides found in installed modules as well as site-specific guides from the project folder. In this way each website could have a complete user help guide that covers all available functionality and nothing extra, and is accurate to the installed versions.

The docsviewer module can probably do the bulk of this already but some changes needed might be:
  • Allow modules and project code to remove or replace user help pages and insert additional pages in specific places
  • Show user help within CMS (i.e. in a LeftAndMain view with Help as active tab)
  • Docsviewer would become a dependancy of Installer
  • We might want to apply some kind of SemVer approach to the file/menu structure of user guides so that they're only moved or renamed in major releases - this way module authors should be able to reliably target items for replacement or insertion
Should we look at setting this up? I know it would make life easier for me - I could say "Just click the Help button" a lot more often :)

Nicolaas Thiemen Francken - Sunny Side Up

unread,
Dec 7, 2015, 8:15:18 PM12/7/15
to silverstripe-dev
+1 

User driven "how to do something", FAQ style, help is best I reckon:

* how do I add a page
* how do I delete a page
* how do I change the address of a supplier
* where can I find the list of customers
etc... 

It would be great if both content editor and developer could, super quickly, add and edit "how to" FAQs within the HELP tab of the CMS. This should include space for screen shots and screen casts. 

Nicolaas

Mike

unread,
Dec 8, 2015, 4:19:05 PM12/8/15
to SilverStripe Core Development

Wordpress has one way of bringing in help by a dropdown at the top of the CMS with external links off to their documentation. I'm not sure if it is editable by the CMS users but it is a start : )

A lot of SilverStripe projects (well the ones that I deal with anyway) are all fairly customly built for the client and who's job it is to keep this documentation up to date gets blurred depending on who you talk to in the project.

I'd also like to see documentation that is both developer and CMS user friendly, both can easily update these docs. They are shown firstly in the CMS and then have links to external site(s) and videos where relevant so content isn't duplicated. This maybe hard to implement but quite often in projects it is up to the company or content users themselves to document their internal and content processes rather then the developers who I'd see their documentation is more feature based?

I'm not sure if the docsviewer module would really be cut out for this job?

Marcus Nyeholt

unread,
Dec 8, 2015, 4:38:14 PM12/8/15
to silverst...@googlegroups.com

http://addons.silverstripe.org/add-ons/webtorque7/adminhelp

Provides some useful in-cms help options.

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.
To post to this group, send email to silverst...@googlegroups.com.
Visit this group at http://groups.google.com/group/silverstripe-dev.
For more options, visit https://groups.google.com/d/optout.

Jonathon Menz

unread,
Dec 8, 2015, 4:49:49 PM12/8/15
to SilverStripe Core Development
Hmm I hadn't really considered being able to edit user guides within the CMS - I figured developers would be writing the user guides and I was just thinking of how to improve on what already exists rather than re-inventing the system. 

What I was envisioning for the user guides is that the basics are automatically filled in from installed modules and updated when the modules are updated, and custom features are documented by developers in their own markdown files. It would be a good default for getting some basic and accurate user help in place without too much work.

User guides that are editable from within the CMS sounds like a great idea (basically a Wiki module) but I think automatically updating the user guides when modules are updated might be really difficult if all the text for the user guides is editable in the CMS. So it would probably require a greater user effort in entering the initial content and keeping it up to date over time.

I think it would be pretty hard to combine these two approaches so I think we're talking about two separate help systems - but maybe they could complement each other? So you could have two separate help items in the menu, maybe you call one 'User manual' which displays the developer-contributed 'standard' user guides, and you call the other one 'Tips' which shows user-contributed / client-specific Wiki content.

In that case I think only the Docsviewer approach should be included by default in Installer and Wiki could be optionally added on. You could edit your requirements to just have the Wiki though if you don't need the developer-contributed docs.

Richard Rudy

unread,
Dec 8, 2015, 4:59:19 PM12/8/15
to silverst...@googlegroups.com
I'd love something like the DocViewer for user help. I currently use the DocViewer to build developer docs for larger project, but I often resort to PDFs for user docs. 

If the a user help module could crawl the directories looking for a user doc directory and build a help pages it would be great. That way module devs can use established patterns moving forward. 

Sent from my iPhone
--

Paul Clarke

unread,
Dec 8, 2015, 6:43:48 PM12/8/15
to SilverStripe Core Development

I've been thinking about splitting the help into the sections you are in, there would still need to be a global help though to access things that aren't section specific, this would be ideal for modules which would have their own help. The current Help call-to-action gets overlooked, and there's times when people don't even know it even exists.

I like the ideas mention above. It would be great if users of the CMS could also contribute these docs, but not through markup—even if it was only to recommend amendments.
Having a basic wiki set up which could be connected to the CMS would be great, with the ability for users to add their own pages based on custom development which would be private to that specific site.

+1
 

Mike

unread,
Dec 9, 2015, 4:33:08 PM12/9/15
to SilverStripe Core Development
@Marcus - thanks! I've had a quick look at the module and it is a great start. I might see what changes I can do to attach help content to pages but it shouldn't be too hard to add and possibly submit as a patch to the module.

@Jonathon - I think there is room for both custom project documentation and links off to the userhelp documentation. The adminhelp module is a great step forward for this custom documentation.

I'm thinking about looking into importing the userhelp into the cms using this module (or another option) so users don't have to leave the cms to get help, rather then having two separate help items in the menu which I think would be really confusing to a user!

I'd like to see a world where developer made user docs and and custom user docs live in harmony :D


On Tuesday, 8 December 2015 11:59:13 UTC+13, Jonathon Menz wrote:

Mike

unread,
Dec 9, 2015, 4:47:24 PM12/9/15
to SilverStripe Core Development
Has anyone got an API working with the docsviewer module? This would be handy to pull content from the userhelp site into the CMS.
Reply all
Reply to author
Forward
0 new messages