In the web app, it seems an entry or an asset is always in one of these four states: Published, Changed, Draft, Archived. (As shown in the “Shared views” list on the left of the page.)
I haven’t seen any Contentful documentation that describes these states: what they actually mean, and how entries/assets transition between them.
What are the differences between “Changed” and “Draft”?
Is “Changed” the same as the “Updated” shown in entry/asset lists? (It seems to be: if I filter entries by “status: Changed” the list shows me those where the status column says “UPDATED”.) Why does it have a different name?
Does the Content Preview API just show “Draft”? Or “Changed” too?
Except… I can manually change an entry from Published to Draft. So some Draft entries used to be published.
What’s the value of distinguishing between “Changed” and “Draft”? What functionality do we, as users, gain as a result?
This matters because your documentation (for example, see Preview API) talks about “the latest draft”. As a user (both of the API and the web interface), I need to interpret those words somehow, and the natural interpretation is that “draft” in “the latest draft” means “Draft” as in “the Draft status”. This doesn’t seem to be the case, which leads to confusion.
OK… Some recommendations:
Decide whether to use “Changed” or “Updated”, and be consistent everywhere. Reducing the number of jargon words, especially jargon words that are synonyms, reduces the user’s cognitive load.
Decide whether there’s a meaningful (to users) distinction between “Changed/Updated” and “Draft”. If not, merge them to “Draft” in the UI and doc. If there is, document it somewhere and make sure the doc and UI use the correct terms in the correct places to reduce user confusion.
Add documentation and UI that describes each state, including its relevance to things like the Preview API, to help the user’s mental model.
In UI, be explicit about actions that change state. For example, when I edit an archived entry there’s a button labelled “Unarchive”. What happens if I press it? I’m guessing it changes state to Draft, but since it was previously Published, it might go straight back to Published. I can’t tell in advance, which is unsettling.
(What happens: pressing “Unarchive” changes state to “Draft”, the button changes to “Publish”, and I see a link “Discard changes”. What does “Discard changes” do here? No idea. Does it change the entry back to “Archived”? Well, when I click to the Content tab, then click back to edit the entry, the “Discard changes” label has gone. If I go through the loop again: Archive, then Unarchive, and then click “Discard changes”, I see a “Discarded changes successfully” alert but the entry’s still Draft. So, I have no idea what that’s all about. What, if anything, has been discarded? Anyway, that’s a separate issue.)
Thank you for the note! I just edited the summary with your reminder . In any case, Draft would be those entries that are simply not yet published.
Changed relates to published content that was modified. In the case of Drafts, these are all unpublished (i.e. cannot be delivered through the CDA), therefore the distinction between them.
Also, thank you so much for all the awesome feedback. Although there may have other considerations as to why this particular nomenclature exists, I’m prompting directing this to our product team to investigate your recommendations