feature request - page read status - user's browser remembers what user has read #2379
ptolemy001
started this conversation in
Ideas
Replies: 1 comment
-
This is not a feature we will be implementing into MkDocs directly. I have moved this to Discussions in the event that anyone wants to discuss how this might be implemented in a third party theme and/or plugin. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Hello,
I've searched for this through all the plugins and the mkdocs docs, but haven't found anything relevant. So I opened this as an issue in github.
This feature proposal has the intention to resolve the very common issue of user's brains and current content of documentation getting out of sync, and no easy way to reconcile them again.
If this feature proposal materializes, the result should be that 1) authors can effectively communicate only relevant changes in documentation, 2) users can know exactly what they already have read and [not] understood.
It is natural that if a documentation consists of more than a few paragraphs, the user is not going to remember which sections he has already read and understood.
It is also natural that if documentation is to be an "mental interface" (through reading comprehension) for a user to use a documented system, when the system and its documentation changes, the user should be presented with a clear overview of what exactly has changed.
The suggested feature / plugin is to deal with the dynamics of two areas of change:
The envisioned method of accomplishing this is a (long) encoded string stored by the anonymous user in his browser for his own purposes (either as a cookie or as a bookmark with a long URL parameter), where such a string encodes what the users wishes to remember about a page / section / paragraph or another element in the presented documentation.
Most often, and by default, the user wants to remember which sections he:
a) read but not 100% understood, or
b) read and 100% understood, or
c) never wants to pay any attention to (when such a section's purpose is to carry a topic irrelevant to him)
d) wants to keep tight lookout for any changes (even cosmetic), or
e) wants to keep lookout only for changes which sometimes impacts use of the documented system, or
f) wants to keep lookout only for changes which always impacts use of the system
While the problem of user not knowing what has changed in the whole group of (d,e,f) could be handled purely by the server side by presenting the user with some kind of "html diff" or "diff of sources" of various versions (assuming that the user as a way of remembering which version he as read already), the a, b and c issues cannot be handled by server-side only, as it is the user side which must hold historical information about what the user feels his comprehension and wishes about each piece (section, page, paragraph) of the documentation.
Also note that such encoded string could also be used for more useful searches like e.g. "exclude from my search the sections I've already read and understood, and include those that I haven't understood yet".
When a user loads up a page with such a bookmark or cookie, the individual pieces of documentation may be presented to him in different color of background, indicating:
"This section has changed after you marked it as read and understood", or
"This section you haven't checked off as read yet", or
"This section has new but only cosmetic changes since you marked it read"
Please don't by shy to reply with your thoughts,
regards,
Ptolemy001
Beta Was this translation helpful? Give feedback.
All reactions