docs
docs copied to clipboard
[Docs RFC] Improve add_dimension OLD documentation
In add_dimension() OLD syntax I see some of the improvements possible:
- If we look to new add_dimension syntax documentation at the top there is "Note" in rectangle to suggest user also checks the "old" syntax. But on "old" web page there is no note, that user should consider using new syntax. I suggest to add "Note" to the "old" add_dimension web page that point to new add_dimension web page.
- Some wording of multi-node are obsolete, or if you don't want to change this "old" syntax web page, then I suggest to add "Note" at the top of web page to indicate that multi-node is discontinued. This may be more appropriate, because this old syntax is intended for users that are still using pre v2.13 product and may still use multi-node configuration and are looking for documentation how to change setting.
- Multi-node is obsolete.
- There is no warning anymore on new add_dimension web page, that still exists on "old" add_dimension web page. Probably this "Warning" is obsolete and can be removed. Or write for which TimescaleDB version is this warning still valid. Maybe for users that are still using some older version of TimescaleDB, this may be useful info.
- Multi-node is obsolete. Maybe on the top of web page there is some missing "Note" why should somebody use old syntax (to have the same commands on multiple versions that may be used in company), but it should be suggested to use new syntax. Maybe also add what type of partitioning is used if old syntax is used, indicate that by_hash will be used and maybe suggest user to use new add_dimension syntax if user wants to use by_range.
- May I also suggest to announce deprecation of old add_dimension syntax in order to reduce confusion what kind of partitioning is used (by_hash or by_range). I am not suggesting to discontinue this syntax, when or if, that is your decision. But if you do intent to remove support for old syntax, then announcing is a good way to go, that users that accidentally reach to this web page (by web search e.g. Google search) start using new syntax. In deprecation announcement it can be written that it is suggested to use new syntax, and old syntax will still be supported for few versions. If you decide to announce deprecation, then I suggest to put some "Warning" box on top of web page like: Deprecation, use new add_dimension syntax.