Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs RFC] Improve add_dimension OLD documentation #3087

Open
igor2x opened this issue Mar 23, 2024 · 0 comments
Open

[Docs RFC] Improve add_dimension OLD documentation #3087

igor2x opened this issue Mar 23, 2024 · 0 comments
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@igor2x
Copy link

igor2x commented Mar 23, 2024

In add_dimension() OLD syntax I see some of the improvements possible:

  1. 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.
  2. 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.
    image
  3. Multi-node is obsolete.
    image
  4. 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.
    image
  5. 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.
    image
  6. 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.
@igor2x igor2x added documentation Improvements or additions to documentation enhancement New feature or request labels Mar 23, 2024
@billy-the-fish billy-the-fish self-assigned this Mar 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants