Docs audit [April 2026]: Review docs - metadata update only#3297
Docs audit [April 2026]: Review docs - metadata update only#3297C-Achard wants to merge 10 commits into
Conversation
Installation page
…ril-2026-metadata
deruyter92
left a comment
There was a problem hiding this comment.
Reviewed all comments and completely agree with the assessments and proposals.
| visibility: online | ||
| status: viable | ||
| recommendation: move | ||
| notes: "It seems the beginner guide section is more of a GUI step-by-step. As such, it should be moved to the GUI section, and merged/integrated with the contents there. The content is useful, but making it clear that this is for the GUI would reduce the confusion of a beginner guide being in fact rather central GUI use instructions." |
There was a problem hiding this comment.
I agree, but should we make a separate beginner guide as well then? What should it look like? I assume that beginners that are not very familiar with python will start with the GUI anyway right?
There was a problem hiding this comment.
Yes, most likely that's why the beginner guide ended up being a GUI guide. I'm not sure if there would be a lot of demand for conda basics ? Otherwise a super useful beginner guide could simply explain a bit what DLC projects look like, and provide an overview of concepts besides actually using the API/GUI. That would take some time though, but it could be useful. Perhaps focusing on current docs is best for 3.0 for now
| visibility: online | ||
| status: review_needed | ||
| recommendation: update | ||
| notes: "While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead of re-suggesting commmands but then still saying to read the install page... Also, the GUI is likely used by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. Addendum: it seems the beginner guide section is more of a GUI step-by-step, as mentioned earlier in this comment. I would suggest merging/moving and adding links in the present doc, which would make it less of a video list and more of a proper GUI guide." |
There was a problem hiding this comment.
I 100 percent agree on the idea of 1 file per GUI tab
There was a problem hiding this comment.
@deruyter92 Should I open another PR to rework this ? There's also the single animal guide to finish
| visibility: online | ||
| status: viable | ||
| recommendation: archive | ||
| notes: "This is a bit stuck between minimal guide and quick start, as the lack of explanations makes it more into a catalogue of commands (which is an API docs responsibility), and a proper quick start guide that gives users a proper sense of the workflow. This should either be expanded greatly or simply archived. For simplicity, I recommend archiving." |
There was a problem hiding this comment.
agreed. We should proceed with the API docs soon as well. Can follow the 3.0 release I think
…ril-2026-metadata
Motivation
This PR is part of a broader documentation auditing process, which aims to offer a clean, systematic review of current documentation, suggest potential improvements, and start updating critical pages.
See:
Suggested merge order:
Scope
Provides a comprehensive review and suggested actions for current docs using the newly introduce tooling.
visibility,status,recommendation, andnotesfields to nearly all documentation files, specifying whether each doc is online, outdated, viable, or in need of review, and providing actionable recommendations (e.g., archive, move, update, keep, verify) to guide future maintenance.View the review CSV file for the latest overview