reorg docs operate

[fenekku]

Reorganize the Customize, Develop and Deploy sections into Operate section (and other sections).

Notes

This reorganization pass is probably more dramatic than the previous ones.

• Combines elements of the former "Develop" section with elements of the former "Customize" and "Deploy" section into one section that targets instance operators as the audience.
• Goal is for this corner of the documentation to be the main one-stop-shop for operators (shouldn't have to go further 80% of the time)
• Pushes for locality of information to achieve this
  • Helps readers by not losing them across 5 far apart locations
  • Helps writers similarly to concentrate their configuration documentation
• Surfaces some sections in the docs UI even if not surfaced in the directory structure: this is usually to bring attention to sections for readers, but let writers have less constraints
• Removes add_javascript.md since completely covered by custom_code.md
• Places migration creation in maintenance/internals (was debating placing in maintenance operations)
• Place infrastructure.md in Operate/ops section
• Place how to make a security fix in Contribute/code section
• Modifies the Install section only so far as to harbor docs not fitting the Operate section
• Standardizes the images folder to be imgs and placed closest to image usage in Operate (not really touched image folder of other sections)
• The higher level directory/file structure is more set, but the lower level directory/file structure is more amenable to content move/rename.

Review divisions

Those are artificial savepoints to help with the review. Will squash all of them when merging.

• docs-reorg: move Releases before Reference
• docs-reorg: add operate/ops section
• docs-reorg: add operate/customize section
• docs-reorg: add operate/code section
• docs-reorg: rm customize/, develop/, deploy/ sections
• docs-reorg: update references
• docs-reorg: update install/ section
• docs-reorg: move infrastructure, security fix, migrations

Screenshots

Home page

Operate section

Demosite

Demosite (all reorg so far): https://fenekku.github.io/docs-invenio-rdm/

Up next

Reorganize the "Install" section into "Getting Started"

[tmorrell]

Thanks for these great changes! I think the reorg overall makes sense. I mostly added comments on introducing the environment variables, and whether that should be included earlier in the flow.

[tmorrell]

Looking at the section order...I think this should be before "Customize metadata model". Settings like TRUSTED_HOSTS are going to be needed by everyone who is standing up an instance, while only some people will need to get into metadata.

This could also get broken up into more common and less common configuration elements...but probably not needed for the initial reorg.

[fenekku]

I think the "common and less common configuration elements" is indeed the right strategy to address that one. We could highlight the common/needed configuration elements in either the upcoming "Get Started" section and/or the Operate/ops/deploy.md section (once the Get Started section is done).

This "Configure everything" section is a bit of a catch-all-else section for all the knobs and levers InvenioRDM provides that were not covered yet. Since it is so big and will grow, pushing it towards the end of the Operate section feels like the right place: it's a reference section of everything configuration. More important configurations like TRUSTED_HOSTS and so on, have to be highlighted/linked to from elsewhere to make sure they get the right attention though as you've pointed out.

New Ticket: #768

[tmorrell]

I'd use "custom field(s)" instead of "field(s)". Since they aren't treated like other fields.

[tmorrell]

I'd lean toward putting configure here, or even before deployment. The beginning part with environment variables is really needed before folks start moving toward deployment.

[fenekku]

Right, having a section for the subset of configurations really needed before deployment would make sense here. As mentioned above, I will loop back around to this one when the Getting Started section is done to see how the difference splits. I am saying this because some of those configuration used to be in the install section, so I wonder how they will sit when that section gets transformed 🤔 .

[fenekku]

Updated. I will do a content pass to highlight the needed configurations as part of #768 .

[fenekku]

and demosite deployed: https://fenekku.github.io/docs-invenio-rdm/