react-client
react-client copied to clipboard
hedgedoc
(Re)declare technical terms
If you read the issues #117 #103 #118 #119 (and some others I didn't found), then you can see that some terms are used for different things or can be confused. That's why I opened this issue. We should declare some terms:
History
Currently when we say "history", then we mean the history of recently visited notes. That can easily confused with the note revision, because that's a history too. That's why I propose: From now on we call the note history "recently visited notes" or "history of recently visited notes", but not "history" alone.
Local and remote history
Currently when we say "local" or "remote" history, then we mean "the locally saved history of recently visited notes for an anonymous user" and "the recently visited notes of an logged in user, which is loaded from the server". There is no problem with the remote history, but with the local history. If we really plan to save notes on the local machine as stated in #103 we shouldn't use the term "locally saved" or "local history" for both. Because it could also mean "the history of locally available notes" That's why I propose to call them:
- anonymously visited notes / recently visited notes as anonymous / history of recently visited notes without login
- user history of recently visited notes / history of recently visited notes as logged in user
- synchronized notes / list of synchronized notes
What do you think?
Uhm, to be honest, I'm not sure what you are referring to, when checking the issues above, because the majority of them doesn't seem to be talking about anything else than what we currently call note history, and some don't mention the note history at all or aren't even discussions. But anyway, yes, I know about the discussion we recently talked about.
Generally speaking my main problem with all the new "terms" is, that they aren't actually terms. They are descriptions. A term can be translated to German and result in a single word, that doesn't contain spaces and is understandable. I.e. "note history" -> "Notizhistorie"/"Notizverlauf" vs. "anonymously visited notes" -> "Anonym besuchte Notizen"
In first place that seems useful because it describes the situation, but it becomes a big hassle when you realize that you have 3 terms talking about the same place in the UI.
For the problem of saving notes to the local machine, the obvious candidates are: "offline notes", "downloaded notes" or "local notes". Depending on how they end up being implemented one or another might makes more sense, but I don't think they should have anything to do with the word history.
About the list, this should be a simple filter in the notes list (given we have that at some point) or note history, where simply a filter is applied for offline-available notes.
I think as in most cases: Less is more and renaming things is hard. Therefore I would try to keep it the way it is, even when that means, that some people get a little confused. (Exposing the name a bit more could help to solve this specific problem)
These names are examples. We had enough discussion where someone was confused because the names weren't unique. That's why I want to define clear names, that everybody understands and document them. (they don't have to be that long. Like I said the one above are just examples)
I am strongly for changing the history term cause I have it already wrong in my memory and it will probably always be like that.
If you talk anything history for me I am always thinking about the note editing history and never about recently opened notes. It is maybe the correct analogy to browser history but I can't view web pages in the past with my browser alone.
I am sure there are more people out there like me and the constant confusing is really frustrating.
notes I visited could be "recent notes", but I would like to note that browsers call this "history" or "chronicle" regularly.
Revisions of a note could be "edits" as well, or "versions" because it refers to different versions of the same document. From a frontend perspective I don't have a preference either way in this case.
To me, "history" (documents I recently used) and "revisions" (old states of the same document) fit well.
I am repeating myself. A browser has no history of the page you are currently visiting so there can't be any confusion. Edit and version also allow appending history which fully describes them and does not solve the problem.
It has not, but that would still mean the existing history of a browser is very much like the current history term in CodiMD. Things I have visited before.
CodiMD adds another dimension to that, the versions, changes or the log of a single document. These are terms that are consistent with things in git for example, where you would do a git log -- some/path.md to find the changes made to a single file.
If history is deemed too confusing, I would argue that it must be kept out of both things. A suggestion to achieve that could be:
- recent (local|remote) documents (for things I visited or edited)
- versions (to show the changes made to a document over time)
This becomes superfluous by the new explore page that doesn't use the term "history" anymore?
