docs-invenio-rdm icon indicating copy to clipboard operation
docs-invenio-rdm copied to clipboard

Published 20 hours ago • verified publisher icon inveniosoftware

reorg docs operate

Open fenekku opened this issue 6 months ago • 2 comments

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 reorg_operate_home

Operate section reorg_operate

Demosite

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

Up next

Reorganize the "Install" section into "Getting Started"

fenekku avatar May 22 '25 19:05 fenekku

Updated. I will do a content pass to highlight the needed configurations as part of https://github.com/inveniosoftware/docs-invenio-rdm/issues/768 .

fenekku avatar May 23 '25 12:05 fenekku

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

fenekku avatar May 23 '25 12:05 fenekku