wip[IMP] upgrade documentation

[nmarotte]

Draft PR for pre-reviewed as asked by anv in 3440903

[robodoo]

This PR targets the un-managed branch odoo/documentation:staging.16.0, it needs to be retargeted before it can be merged.

[robodoo]

Pull request status dashboard.

[jcs-odoo]

Hi,

It's great you're dedicated to improve the documentation for the database upgrades, thanks :)

I'd like to discuss this together, to find what's best but I'll already write some things here:

• In general, I think the content is needlessly long.

  Writing for documentation isn’t the same as writing for a blog or another medium. Readers are more likely to skim read until they’ve found the information they are looking for.

  See content guidelines: writing style
  Most of the time the text is written the same way you would talk to someone, or in a long book, or live presentation.

• Bad use of the future tense

• No need to explain again the same thing in all pages. If the info is already written somewhere, it is better to refer to it with custom anchor links or documentation links, rather than rewriting it. Two upsides to this: shorter texts make it easier for readers to find the exact info they need, and it reduces the maintenance of the documentation.

  • For example, re-explaining that Odoo supports the three latest versions --> link to the supported versions page
  • Similarly, I'm not in favor of FAQ sections in the documentation because they duplicate the same content in a different form. Instead, it is best to provide links at the beginning of a page, like a menu ("to do this, consult this")

• I won't accept to put "Upgrade" at the root level of the documentation like this: upgrading a database would be way too over-represented in the structure.

  • Just so you know, we interrupted a restructuration of this install/maintain section as we currently don't have the time to implement it, but we also considered renaming that section "database management", which you may find more acceptable as a parent category :)

• "Advanced" categories are to avoid at all costs: that name is barely more helpful than "miscellaneous". Topics shouldn't be categorized per difficulty but per theme.

• If possible, I suggest the use of group tabs as well for the request processes.

But let's plan a meeting with me and @xpl-odoo to discuss all this (and more), it will be more efficient :)

Again, it's really nice to see your dedication to improving the documentation! 😊

Cheers,
Jonathan

[nmarotte]

Hello @jcs-odoo

Thanks for your input :) Actually the documentation is still a work in progress but I was asked by ANV to request review from you, I should have written it was not ready to be fully reviewed yet

I agree with all of your points and will take that into account when working on this. I'm still in the process of rewriting most parts of the text, as the text was first inteded for a smartclass where the context is different

[nmarotte]

Closing due to #5953 being the main PR, this can still serve as a backup in case I need to copy-paste some stuff