Extensively re-write the scheduled jobs page
Created by: seancolsen
This is a complete rewrite of the scheduled jobs page.
Motivation
I started making these changes while re-organizing the "schedule jobs" content better between the User Guide and the System Administrator Guide, but I got a little carried away.
Before
- Well technically speaking, without this PR merged, there is no scheduled jobs page (because I removed it (somewhat accidentally) while moving some content to the Sysadmin Guide. But before that...
- The old scheduled jobs page didn't mention any specific scheduled jobs.
- Other characteristics of the "Settings - Scheduled Jobs" page were undocumented.
After
- Document specific scheduled jobs. Some things to note about this...
- While some docs exist in the UI, they're only in the form of the default jobs created when installing. So parameters, for example, are documented right in the existing value for the parameters text field which means that if a user changes that text field to make the job actually work, then they lose the doc about what other options are available for those parameters. Similarly, they can delete jobs and lose info about them. I think this UI doc design is very bad here, and I'd like to change the way it works in the UI, but I think the first step is to get the doc into the guide.
-
@xurizaemon submitted #148 quite a while ago to auto-generate this list. I like the approach in this PR better because it provides much more info. I do think it would be nice to auto-generate this info from core, but as it stands now, there's some important bits which are difficult to include in auto-generated docs. For example parameters... some of the info about parameters can be extracted from the
getFields
API action, but not most of the API calls for the scheduled jobs don't have_spec
functions. I think it would be cool to move in the direction of auto-generating these docs, but I think it's going to be a larger project to get them to the level of quality that I think we need here. And I don't want the auto-generating project to hold up this content-reorganization project. - I looked in several places to gather info for the details on these specific jobs...
- Comprehensively document all parameters available for specific scheduled jobs
- Reference docs in the Sysadmin Guide for setting up the cron job and for using cron to call specific scheduled jobs.
- Improve explanation of "cron", from a user's perspective.
- Explain "API call" from a user's perspective (since the UI mentions API calls).
- Explain the difference between a "scheduled job", "API call", and "default scheduled job" which I think is an important distinction to explain because I think it's a little confusing.
- Explain more about job frequency and timing
- Explain how command parameters work, generally (including the syntax needed for the text field)
- Mention the job log
Dependencies
Note that this PR references some pages in the Sysadmin Guide which don't yet exist. (A Sysadmin Guide PR is forthcoming to add these pages, which is why this PR here is marked as WIP.)