Problem

Based on the UX foundation User tests hm://z6MkkGNjfnikRkxK9EaxMPYy3HYxNGkRyXTWxxRtynB2kyeb has directed. there's a general misconception from users around the publishing concept. Basically the idea of publishing one document at a time and understanding its hierarchy is challenging to normal users. What we are realizing is that in order to fix this, we need to fundamentally change the mental model we have around publishing. This project aims to explain this mental model shift and will try to layout a path moving towards this new publish paradigm.

Solution

This is the new idea:

Users wants to make changes to the whole site and Publish the site, not publish individual changes to documents.

The user expects to make changes not only to one document but to multiple documents:

create new documents

create subdocuments

move documents

create links between them

delete other documents

And all these changes are cognitively grouped into ONE change that must be published. This is a big a fundamental change that as developers who understand the permanent data and how it works, it's not reflected specially well.

Publish a Site does not mean now that you MUST publish all changes you did on the site right away. This means that the Publishing context is not about the Document anymore, is about the whole Site. This is Similar to how Git let you change any file in the repo, and before you commit you decide what changes to include on every commit.

This idea makes a few assumptions that we need to accept/understand:

1. Everything that I can edit, should be editable all the time

If the user have write access to a site or a document, this means that the user must be able to edit anything right away. This means that we are going to render the editor for any document the user is capable of writing rigth away, and detect if there's any changes to efectively create internal drafts and keep track of them. the app must keep track of all the edits across a site so when the user want to publish, we can present to the user what are the things that can be published.

This is tricky in scenarios where a user can edit not the whole site but just a section of it, or just one document of a site. Either way, we must do the job of keeping track of all changes (new documents, edits, moves, deletes...) and publish all when the user wants to Publish the site.

2. the Hierarchy of documents is reflected in the content, not in abstract ideas like Directories.

This is based on the idea

Subdocuments are part of the document of its parent

This changes the way users can organize content in their sites. but more importantly introduced to a new concept: hm://z6MkuBbsB1HbSNXLvJCRCrPhimY6g7tzhr4qvcYKPuSZzhno/definitions/unreferenced-documents

Because we need to support current sites, what we came up with is with a dynamic query block at the bottom of each document that will traverse the document content, and will show all the unreferenced subdocuments. We need to do this in order to comply with the new rule displayed above.

Path moving forward

Here I need help because based on this new mental models and ideas and also based on what technically we can do to make sure we don't messed up too much with the permanent data, we need to define the steps towards the final goal. here are the steps I found can work:

create cards of subdocuments (already done. we need to change the order in which things happen but is almost done)

show unreferenced documents below the content

make everything editable: render the editor when the user can edit.

keep track of all changes on the site and publish them in bulk

All these changes needs to be in hand with the UX foundations changes that are mostly UI.

Scope

TBD

Rabbit Holes

As you can Imagine, there are MULTIPLE rabbit holes and edge cases coming with this new mental model. Here are some of them:

If I create a subdocument, this will create both a draft for the parent and for the subdocument. Based on the rules, we should publish both a change to the parent and a changes to the subdocument. but if the user do not want to publish the parent, this means that there are important changes that were not published (subdocuments should live in the parent right?)

Deleting one document means also deleting the card of that document on its parent. do we want this?

What happens with documents with query blocks?

If we are adding links to subdocuments on parents, authors do not have a way to "sort" those links based on data like "latest activity" or "last update". Do we want to allow users to do this?

How authors define the way they want to see the subdocuments? is that defined at document level or at card level? how will this be catch by new links added?

I'm sure there's a combination of changes for a particular site that will be incompatible to do/undo (like "publish all parents but no children" or publish parent with rearrange blocks but no children"). what should we do here?

What if one of the publishes goes wrong, should that make the whole publish fail?

No Gos

TBD