[REF] l10n: PoC doc restructure for CO

[StraubCreative]

Cherry pick of #2659, now pointing to the correct base branch.

@StraubCreative and @samueljlieber found the latam l10n docs could use an update/cleanup to break apart the single long-form article for each l10n module.

This PR was created as a proof of concept to improve the structure of latam l10n docs so they are more consumable and follow a similar flow to the rest of the documentation. The proposed document structure is for Colombia only in this PR, although this structure applies to all latam l10n countries.

The details of the proposed document structure can be found here, the structure is summarized below:

localizations
└── colombia
└── colombia.rst
..........├── configuration
..........├── reports
..........├── workflows
..........├── configuration.rst
..........├── reports.rst
..........└── workflows.rst

colombia.rst is the main l10n doc providing an introduction, video tutorials, scope, and glossary of terms.
|_ configuration.rst outlines the steps to install the localization module and the basic configuration setup.
|_ workflows.rst outlines the main workflows of the module, common problems/errors, and more advanced workflows.
|_ reports.rst outlines the financial reporting process of the module.

Each nested RST doc contains it's own media folder with the same name.

The goal is to build a working model, and then replicate + keep this consistent structure throughout latam l1on docs.

EDIT: summarized doc structure, removed configuration doc/folder, merged content into colombia.rst per the ideal User Doc Structure guidelines.

[robodoo]

Pull request status dashboard.

[StraubCreative]

Initial commit: 93428cc

• removed colombia_ES.rst
• reorganized images to properly named folders instead of general colombia folder
• small content updates on top of cherry-picked commit 497206d

[StraubCreative]

Updates in f6c29c3:

• addressed failing CI checks
  • removed deleted file path from localizations.rst
  • fixed image file paths inconfiguration.rst

PR passes CI Checks now— free to continue with layout rebuild and content updates 🚀

cc: @samueljlieber

[StraubCreative]

@odoo/accounting-doc-review this is still a work in progress but worth bringing up on your radar.
Will ping you when it's ready for review.
Thank you 🙏

cc: @jcs-odoo

[chiaraprattico]

Hi guys, I started my review, but I guess this is not finished, so I'll wait for you to confirm it once it's done. :)

Thanks!

[samueljlieber]

Hi @StraubCreative, thank you for getting this PR up to date!

Updates in 4265818:

• Added content to the reports.rst doc
• Removed the Glossary and Scope sections from colombia.rst
• Enabled the table of contents in colombia.rst to show links to Configuration, Workflows, & Reports

[samueljlieber]

56e0af8 to remove 16.0 specific images ➡️ 8c56efd to add 14.0 specific images.

Hey there @StraubCreative, @vbe-odoo, & @ren-odoo 👋 can you please review the entire CO L10n content and add suggestions as necessary?

Thank you everyone for your continued hard work on this!

[ren-odoo]

Hi @samueljlieber

I left some minor suggestions, but general structure considering the new approach, looks good :)

There some images that are outdated, mainly because this localization has have several changes since the first documentation was created, there are well important new workflows and use cases that we want to add to the website documentation. Should we include this improvements and additions in this PR or should we handle this on a diferent PR once the new general structure is merged?

cc. @StraubCreative @vbe-odoo @fvz-odoo @and-Odoo

[jcs-odoo]

Hello :) just a few small comments after having scanned the pr, not in detail.

I wonder if splitting the page into several smaller ones works well here. Maybe it can, but it feels wrong as it is now...

The "Colombia" category page is empty and would only have a link to a youtube video. If there was some useful content redirecting to the subpages, then why not, but then it would probably become redundant with "workflow" and "reports".

Well, have a good weekend and... see you next year 😁

[samueljlieber]

Thank you @jcs-odoo and @ren-odoo for the suggestions 🙂

Updates in f22a6e5:

• Reworded the video tutorials description
• Moved the module list to configuration.rst and removed version specific copy and image
• Removed the guilabel from reports.rst
• Added an Introduction description

I added the introduction description as a possible solution to @jcs-odoo comment, let me know what you all think.

@ren-odoo regarding your comment about adding new workflows and use cases in this PR, I think it would be best to handle this in a different PR once these structural changes are merged - wdyt @StraubCreative?

See you next year 🥳

[samueljlieber]

Updates in adcafb4:

• fixed merge conflicts due to new Fiscal Localization structure

[samueljlieber]

Rebased to latest in 1849105 and reviewed the structure changes again.

A handful of the images in this PR are a bit wider than they should be, but are already too heavily compressed to resize. Ideally we should retake the following:

configuration/:

• access-electronic-invoice-sequence.png
• electronic-invoice-sequence-prefix.png
• partner-fiscal-information.png
• partner-rut-doc-type.png
• retention-tax-types.png

reports/:

• certificado-de-retencion-en-iva-report.png
• certificado-de-retencion-en-fuente-report.png
• certificado-de-retencion-en-ica-report.png

workflows/

• zip-invoice-chatter.png
• updated-invoice-status.png
• electronic-invoice-workflow.png
• carvajal-invoice-xml-chatter.png

[StraubCreative]

Quick touchups on b478f96. Checks pass ✅

@jcs-odoo and @odoo/localizations-doc-review team,
At long last this is ready for your review 🙏

The purpose of this PR was to break apart the CO l10n documentation into individual RST files so the content was more digestible in steps for users. After working with @ren-odoo 's team, this was the way we thought it would best make sense right now, and for developing further on future PRs.

If approved, we'd expand on these docs more for CO with more in-depth written instruction, and would duplicate the PoC structure to other LATAM l10n documentation (PE, AR, EC, etc.), as the opportunity arises.

Thanks in advance for your review and thank you @samueljlieber and Team @ren-odoo for your help!

[jcs-odoo]

Hi, and thanks again for all the great work!

I still think all the content could fit on a single page if there is a nice intro that introduces the various sections of the page.

If you have a look at the structure of all three pages, they all have a single h2 heading, which defeats the purpose of having one at all somehow. Also, the reports page is still ultra short. Combined into a single page, these headings become sections that look well organized.

I'll force-push this branch in a minute. I kept changes in separate commits so we can easily pick or drop any if needed. :) We'll squash them all into a single commit before merging the PR.

• 1st commit is the original one (I also rebased the branch since there was a bug with werkzeug on older bases)
• 2nd commit: some changes and fixes (most are commented in this review normally)
• 3rd commit: moving everything to a single page, to see how it would look like
• 4th commit: adding some custom anchors to headings to link them in the intro of the page, as suggested previously in an old comment (although I hoped at the time we could use cards) but it would certainly need to be improved. It's just to give you an example
  

I agree 100% that longer docs can be split into several ones, but here it still seems a bit overkill, IMO. Also, longer pages could sometimes have less content and go straight to the point, have links to other pages that already describe the same flow (I'm not saying this for this colombian doc, but in general), and have fewer images (for example the Mexican localization)

Anyway, let me know what you think of it. :) Maybe I don't see something.

Cheers!

[jcs-odoo]

This section won't be useful in more recent versions of the doc since the packages installation has been ultra simplified (and will be described in the fiscal_localizations parent page (cc @chiaraprattico @dade-odoo @toaa-odoo )

[jcs-odoo]

missing the other modules that can be installed

[samueljlieber]

Hi @jcs-odoo 👋 thank you for the informative response and commits! I agree with your changes, and I have another PR #4425 that improves the content which I will now update to follow the structure you have implemented on this PR.

I'm happy to squash commits 1, 2, 3 and 4 they look good to me 🙂 please let me know if you would like me to do so!

[samueljlieber]

Hi @jcs-odoo and @odoo/localizations-doc-review this PR is ready for your final review. I have another PR #4425 waiting on this restructure that will improve the content of the colombia.rst doc. Is there anything I can do to help move this PR along? Thank you 🙂

[jcs-odoo]

@robodoo r+