A proposal for "dogfooding" Serenity documentation

This wiki page is a belated contribution to the discussion thread entitled "Is there a hidden documentation site?"

I've been involved in a lot of programming communities. Serenity is one of the good ones, and Serenity code is very capable, but it's hard for new people to get started. There is a lot to learn, and a lot of different places to find the answer within the docs, tutorials, etc, and not all of them are relevant to the version of the framework you're trying to use. So, how can we make this better?

General Proposal

I propose that Serenity templates (both free and Pro) include a Help module, in which the current Serenity documentation can be included as data.

This is what is known as "eating your own dogfood" in various vendor developer teams. You build the product using the product. Serenity already does this, in many ways. Serenity.is is created in Serenity, and the blog is an extension of the website Serenity project.

My personal vision for this, and I have included all my code attached to this post, involves two sides:

Serenity_Proposal_HelpSubsystem_LSN.zip

the End User side of the docs
the Authoring, or Administrative, side of the docs

Schema and Design

There are four tables required in the Default database schema.

Help Topic is where the content is stored, and where it is edited as HTML. This table has a TOCIndex column, which defines the order in which topics are shown to end users. In my version, TOCIndex is a string value that functions like a Dewey-Decimal or outlining value, so that it is subdivide-able as needed. For example, the topic 1.0 would come before 1.0.1, and typically 1.0.1 would be a sub-heading or sub-topic within 1.0.
Help Category also classifies Topics, but in a stricter way. Category is 1:M with Topics.
HelpCategoryRoles allows the restriction of a Category to one or more application roles. In my current design, which probably isn't as elegant as it might be, if there is no row in this table matching a Help Topic, that Topic is unrestricted.
HelpImage allows for the upload of associated images to be inserted into the documentation content.

How does this help Serenity developers organize documentation?

First, there should be a Developer category of docs, and the template should ship with topics already filled out in this category. The portion of the existing documentation that applies to the current version can be gathered up and dumped into topics with some effort, which I think the community (including me) would be happy to supply. Once it's there it's pretty easy to edit, whether programmatically or through the UI.

Feel free to subdivide Developer docs into different categories if you like, but with proper TOCIndex organization it probably won't matter and will be easier to organize, and separate out from end-user docs created on a per-application basis, whether to be restricted or just deleted in production would be the developer's choice. I'll make an exception for the API docs, as discussed below, but that is the only one I'd separate out.

This content can be provided within the template as migration scripts, or (in my world) it would be generated in SQL from the existing rows when the template is refreshed.

Second, the API docs are clearly already generated and honestly in a lot of sections they're not currently that helpful. However, generating them into upsert statements probably won't be hard to do. This section of the docs would be in a separate Category to keep the signal-to-noise ratio in Developer category as high as possible.

Third, anybody could propose a correction or improvement to the docs by migration or SQL script. To be accepted by the Serenity owners in the same way as they would accept, or not accept, any other code change proposed by a community member.

What are the other benefits?

The user experience that developers have, when using the docs as end users or authoring docs, will provide valuable examples. I don't pretend that my own code is the best it could possibly be, but it has been built according to instructions gathered from all over the Serenity tutorials and sample code, and it offers a pretty good model.

Also, I do believe that building documentation into the final end-user apps should be made as easy as possible to encourage developers to provide documentation! While it's true that Serenity apps provide an intuitive UI, any non-demo app has lots of functionality related to business logic, which needs explanation. And that documentation should be within reach, while you're using the app.

Related to this point, while not shown in the sample code, my implementation includes the ability to put the proper "page" of the docs at the user's fingertips, in particularly difficult functions, like this:

var dlg = new HelpDialog(); dlg.loadByIdAndOpenDialog('Job-PipeClass Requirement Set');

... this is why, although it might seem odd, the readonly, end-user entity v_Help has the string field Title as its Id field, not the original Id value of the Help Topic table. It makes for much more readable code.

How to incorporate my sample implementation into your test app

SQL Portion

In the zip file I'll attach to this wiki page, there is a SQL script named initialize_db_system_HelpSubsystem.sql which is meant to be run in the Default db.

Note that it is SQL Server specific; I haven't done anything about making it generic so, but I don't think it does anything that couldn't be done in other SQL dialects.

This script does the following:

creates the four Help tables.
creates a V_Help view that provides an initial readonly entity for the end-user consumption of help content, although at runtime the actual content is provided using a stored procedure, which allows for more functionality. While developing I found it useful to have the view but it might not be necessary
creates the p_GetHelpTopicsForUser stored procedure
creates a second, utility stored procedure, p_RehomeHelpDocContent, which is not exposed directly in the app in any way but makes it easier to handle moving help content between installations.
creates an initial set of two categories and some topics in each:
- General - models end-user documentation and provides a little starter content;
- Administration - models help-author documentation and provides content that explains how to author topics, including an explanation of the p_RehomeHelpDocContent procedure usage.
points to a README.md with the rest of the steps you'll need to take, which I will repeat below, and
indicates a couple of recommendations for continuing as follows:

   -- Additional Administration topics you might add would be instructions on editing user permissions.
   -- These might or might not be system-specific, but Serenity could provide a startup set.

   -- Finally, Administrative topics supplied in the base can be restricted to a Role or Roles if one or more are set up for this purpose.
   -- There aren't any roles currently supplied with the template, so I won't do that.

Web App portion

Here's what's in the README.md file

Add the Help folder to the Common module, fixing application-name part of namespaces, this should be a template item
Add the HelpCategory, HelpCategoryRoles, HelpImage, and HelpTopic folders to the Administration module, fixing application-name part of namespaces, ditto
Run dotnet sergen s
Adjust AdministrationNavigation.cs to expose the Help Authoring entities:

[assembly: NavigationLink(9501, "Administration/Help Topic", typeof(Administration.HelpTopicController), icon: null)]
[assembly: NavigationLink(9502, "Administration/Help Category", typeof(Administration.HelpCategoryController), icon: null)]
[assembly: NavigationLink(9504, "Administration/Help Image", typeof(Administration.HelpImageController), icon: null)]

(note that HelpCategoryRoles doesn't need to be there)

Include the following in NavigationItems.cs, or whatever else you prefer to group Help Authoring:

[assembly: NavigationSection("Administration/Help Authoring", icon: "fa-question-circle",
    Include = new[] { "Administration/Help Topic", "Administration/Help Category", "Administration/Help Category:Roles", "Administration/Help Image" })
    ]

Include a CommonNavigation.cs file with the following, or put it wherever else you want it to be

[assembly: NavigationLink(int.MaxValue, "Help", typeof(HelpController), icon: "fa-info-circle")]

add wkhtmltopdf.exe if you include my PDF buttons and the little HelpTopicReport.cshtml page as part of end-user functionality; you will probably want to customize the report code as well, because it's pretty basic.
If you test out the Help Images functionality by uploading a file named serenity-logo-40.png, the image embedded in the Editing Help Topics (Administration category) should appear. Read that topic and think about whether you need to use the p_RehomeHelpDocsContent procedure, in terms of your expected deployment environment.
Un-comment out any of the pro.extensions items you see in the grid code, if they are of interest to you and you have access to pro features.

Look and feel

So how does this play? Again, there is an end user side and an authoring side.

End User


In my sample implementation, the user gets to Help from a general menu option, like this:	!
Here is what it looks like. The search box's contents is respected by the stored procedure, including a special * value to get only new content, as explained in one of the actual help topics. A topic listing is downloadable in both Excel and PDF form.
Here is what that topic looks like. As you can see, it contains a single, HTML Content/Readonly control, and it allows a reasonable facsimile of itself to be downloaded as a PDF.

Help Authoring


In my sample implementation, the Help Author navigates to his/her functions through the Administration menu, like this:	!
The list of Help Topics allows deleting and cloning as well as an edit button. In the "Pro" version, you can edit the TOCIndex and Category values in-situ. The button with the magnifying glass takes you to the same readonly-dialog that you would see as an end-user.
Editing a help topic (here, the topic is Editing Help Topics, so it is a bit "meta"!) looks like this. Notice that there is an "Edit" tab and a "Preview" tab. The Preview is a reasonable facsimile of the final outcome, although it does remind the author to save in order to see proper content.
Editing for Help Categories and Images is pretty straightforward.