-
Notifications
You must be signed in to change notification settings - Fork 58
Follow up DOC-215 / Updated lead paragraph #1189
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
Discussion from #1181: Simran-B: This is getting out of hand... The part about system attributes was merely a side note, and it's mentioned five times on the page now. I don't see a need to mention it in the lead paragraph, too, which is only meant as a synopsis that can be inaccurate for the sake of providing a general overview. It's also incorrect to say that non-system attributes are excluded (_from and _to are system attributes but can be modified for a long time). romanatarango: I see no harm in repeating the same information to avoid that the user misunderstands it. This is not a poem, it doesn't need to be nice, it has to be unambiguous. Not every user reads the whole page every time she needs to recall something, I guess most people never read the whole page. I want to avoid that a user reads the synopsis ("replace documents with all their attributes"), tries to replace all the attributes (how many people would check further?), this doesn't work, the user searches for a bug in her code for hours, asks the support - just to learn that the sentence in the synopsis is inaccurate. My suggestion does not say that system (you mean system, not non-system) attributes are excluded, it says that non-system attributes are replaced. It doesn't say anything about system attributes at all (a simplification for the synopsis but nothing incorrect). Simran-B: I meant to write:
"It replaces documents with all their non-system attributes" or "It replaces documents with all their attributes excluding system attributes" is the same statement. Depending on the definition of system attributes,
This is not properly defined, and you can find inconsistent behavior concerning system attributes in ArangoDB. If you don't expect users to read more than the subheading, then we need to clearly state in the synopsis what it does and doesn't replace. It does replace _from and _to (if provided by the user). It does not replace the other three, but that is not directly related to the AQL UPDATE and REPLACE operations but a general property of the data model and system. romanatarango: The statements, indeed, mean the same. But these are no statements about system attributes. They speak about non-system attributes. I agree, it should be more clarity about what system collections are, may be worth a ticket. |
Well, there are different ways it could be interpreted
It could either mean that you can replace attributes but not system attributes (including _from and _to) or that you can replace non-system attributes and that no statement is supposed to be made about system attributes. It's ambiguous. I'm not sure how we would define what system attributes really are as long as the server shows different behavior. For example, you cannot index sub(!)-attributes called Regarding the edge attributes, they were true system attributes originally but behave as normal user attributes nowadays in terms of modifying their values, etc. However, they are still special, and they follow the naming conventions for system attributes. Are they system attributes or not? |
Well, it shouldn't be interpreted in the first sense, but you are right, it can. What about: Still short, correct, no ambiguity, details are below. (Btw, "operation", not "operations".)
In an ideal world, one would define system attributes (in some sense) and all other important groups of attributes. And use them consistently, preferably with links to the definitions. What is called "system" and what, say, "semi-system" would be a matter of taste. Quite some work, though. |
Follow up on DOC-215. Updated lead paragraph to avoid ambiguity.