The 'scheduled publishing' feature needs documenting

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.

[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.

[gasman]

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