The help screens are tied into two methods. One, they can be served locally. Two, they can be served remotely. Basically, it's just a matter of adding the appropriate line to the xml help screen control file to enable the drop down menu in configurations to choose where to look for help screens, locally or remotely. The remote part, which we "hard set" by removing the local line of xml for choice is through a J1.5 help server proxy. Runs a custom component, @chisdavenport can fill in more on this. I have no access to this server.

Last year, we discovered old help screens(more of place holders) for 1.7(I think) buried in the /administrator folder and long forgotten. We eliminated them, but in the process broke the TOC because their titles were tied to the formation of the TOC for the main help screen navigation page. @mbabker did a fixed this with a PR to use doc's api to dynamically grab a TOC. That went into 3.2.1(memory) to fix what was broken in 3.2 release.

The whole system was written so a site builder could use default, their own hard coded files or their own remote system. There is also a mechanism for extension devs to add their own files for help screens. Partly why the old files were still hanging around. Everything is connected.

Mark wrote the Selenium/automated help screen generator. Basically, it snaps a screenshot of the admin view and builds a text file of the form fields on a screen and their descriptions. For other languages, if the language files are installed, it will automatically grab a lang specific screenshot and the translated form fields and descriptions when set to the lang. The automated part, the generated files can be uploaded in 5 mins or less with a script. Done, you have help screens. Long term, the goal is to show the help screens automated, with a link or links for a more "how to" based doc on the specific help screen. Those how to docs can be translated on docs and this way everything is integrated.

The current system is no more than a regurgitation of the screen the user is already looking at, so what is the benefit? So an article view how to would be, give your article a name, now an alias, pick a category to place it in, type content in the WYSIWYG editor, use this to do that, etc..etc...

I and other have been working to improve help screens and make them useful. Tracking down missing keys and adding them, working out what was broken and fixing it. So, before we even get into all of this. There are several issues to be addressed first. I'll start with just a couple.

Automated screens, great. Will the core maintainers maintain them? Generate and upload them.
Probably should mention, they aren't fully automated. What do I mean by that? No form fields on a page, no text. So there will still be a need for humans to doc those screens. Devs?
Are the devs now saying they want to write and maintain end user docs too? The help screens are end user and you would be asking a non dev end user to submit a PR for help screens. A translator to submit a PR for their help screens. Honestly, good luck.

Uh oh!

Documentation #3

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions