The 'scheduled publishing' feature needs documenting

[ababic]

After a couple of years of working with Wagtail, i'm still not entirely sure what page revisions are capable of, and what they aren't, and also where the publish_scheduled_pages management command comes into it. It would be great to have some docs to explain things better. Some major points of confusion for me have been:

1. Can you schedule publishing of a revision for a page that is already live, and keep the current revision active until the scheduled time comes? It would seem you can't, but as a developer, I would've thought that was one of the primary benefits of keeping multiple revisions., and should be possible. I'm okay with it not working that way, but it doesn't seem to be explained anywhere, and I'm struggling to guide clients in using the CMS because of that.
2. What happens to a scheduled revision when another revision is published to the page before the scheduled revision's go_live_at date is reached? I think the scheduled revision is considered redundant, and should no longer become live when the time comes. But again, the limitations just don't seem to be explained anywhere.
3. What code is responsible for publishing a scheduled revision when the time comes? I'm guessing the publish_schedued_pages command is responsible for this, but can't find any reference to this anywhere other than in the reference section of the docs. If the scheduled publishing fields are to be present by default, but require a 'recurring task' to be set up in order for them to work properly, I'd expect that to be outlined very clearly in the docs. In fact, I'd probably expect that feature to be disabled by default, and that I'd need to use a setting to turn it on, after setting everything up properly.

[spapas]

Hello @ababic, this is not proper documentation but taking a look at PR #205 should answer most of your questions about scheduled publishing!

[ababic]

Thanks @spapas, that does help a little with the things I was unsure about. We could still certainly do with some documentation, though. I would suggest as a minimum that a 'setting up a recurring task' part needs adding to the setup instructions (I would write it myself, but I don't see myself as technical enough to provide instructions on that - I have very little experience with celery/cron etc).

Secondary to that, would be an additional part in the Editor's guide, that would explain what editors can and can't do in simple terms (e.g. "If you schedule publishing for a live page, this will happen.")

And in addition, a part in the Advanced topics, with more of a technical explanation of how it works, to better arm developers in explaining the feature to editors. (In case they neglect to read the the new section above, or want you to explain why certain limitations exist)

[lacymorrow]

Docs via source-code 🤕 : https://github.com/wagtail/wagtail/blob/master/wagtail/core/models.py#L251

[tomdyson]

How about http://docs.wagtail.io/en/v2.4/reference/pages/theory.html#scheduled-publishing ?

[lacymorrow]

@tomdyson I see no references to live, go_live_at, and expired_at properties among others.

[ababic]

@tomdyson Ooh, I wasn't aware of the additions to the Theory page. While that is certainly helpful, I would suggest moving that out into a separate page in the docs (at the same level as Theory), so that we can build on it. Since I raised this originally (and now have a fair bit more documentation-writing experience), I'm happy to take a stab at that :) Thanks @lacymorrow for bringing this to light again - It had completely dropped off my radar.

[thibaudcolas]

See #8901, which significantly reworks the UI of scheduled publishing, and would be a good occasion to also document how it works for end users as well as developers (we’ve had to research the implementation a lot to get there).

[gasman]

More detailed documentation about the scheduled publishing mechanism has been added in #9263.