Repository navigation
[Doc]: rearchitecture dev docs #26196
Description
Documentation Link
Problem
#26086 puts in a new landing page to make contributing information more discoverable, but is relying on a lot of hand tweaking of links because the contribution docs have a lot of repetition and information at sometimes random seeming level and inconsistency about the scope of the page/section.
Suggested improvement
The docs should be reorganized + consolidated so that that page can pull from tocs. I think the top level bins on that page are the standard stages of contribution, as described by @rcomer #26086 (comment)
- contribute: what can I contribute and help! I'm lost
- setup how do I setup my environment? how do i make a pull request?
- policies: I've written something, what rules do these folks have for what it needs to look like?
To match this structure, I think it's gonna require the following:
- rewrite the specific contributions sections (.i.e. doc, code) in contribute so that they're all "what is this" type intro, as currently code is a deep dive into workflow while docs is super vague, or link out to the specific docs that start with that level of intro and make this doc super meta "i want to contribute & here are the non-type specific basics" DOC: reorganizing contributing docs to clean up toc, better separate topics #27265
- moved minimum dependencies to maintenance section #26218
- clean up dependencies/make them clearer [Doc]: Be more explicit about development dependencies #23831
- figure out what we want to do about the workflow - streamline or gut:
- I've been biased towards we document anything we specifically check for. Also possibly pull in the pull-request non contribution type stuff first section or two of the coding guidelines xref: [Doc]: gitwash deleting main branch #25857
- [Doc]: consolidate coding guidelines #26095
- [Doc]: Sort out doc mechanics/formatting/content guides #26392
- consolidate/streamline triage guidance (this is also spread across a few places)
- adding saved replies to development guide, under triage #23109
- separate out team from mechanics of triage
- next steps in DOC: consolidated coding guide and added naming conventions table #27213
- figure out what we want to do with MEPs - will a contributor ever have to write one or are they historical artifacts?
My preference for consolidation is actually to make folders under devel for at least code and doc (and probably triage) and make a bunch of smaller files for each of the standalone topics & then write a doc against that in an index file that then populates each box. Mostly cause I think it's easier to find docs when developing when they're standalone and not subsections of larger docs.
xref: #22866
Activity
rcomer commentedon Jun 27, 2023
“Minimum Versions” policy looks to me like something only maintainers would need to know when making decisions about changing one. Contributors may need to know what the current minimum version is, but they can get that from the “Dependencies” page. Contributors do not in general need to know how minimum versions are decided.
jklymak commentedon Jun 27, 2023
I think I'm largely OK with the top-level outline (contribute, setup, policies). I think whoever does this should just make an outline with the second level below that and then re-organize what we have (being careful to keep cross links). I actually don't feel this would be that hard as we already have a tonne of awesome material that folks have contributed over the last couple of years.
Process:
What I would suggest for relatively large re-organizations like this is that we should consider moving away from the direct review process. Unlike a feature in the code, which is usually sort of cut and dried, writing documentation always has a component of artistic license, and my experience with the process here indicates that it is gruelling to get big changes through the usual review process because many individuals always have their idea of how to re-organize and/or have many small suggestions. PRs stall out for weeks or months over these, and folks are not willing to merge over them.
A model I think may work better, is for at least two like-minded contributors to propose to the group, and ultimately the steering council or @tacaswell, that they be given license to re-organize a section. They would of course make a PR (or PRs) that can be publicly commented on etc. However, it would be understood that the two people would eventually merge the work, even if there are outstanding suggestions about exactly what has been done. Two people ensures some quality control and proof reading. I'd suggest the amount of work involved in suggestions and proof reading would make the two contributors co-authors on any commits.
I think if we had this as a model for re-orginzations such as proposed here, the job is not so monumental. For instance, @story645 if you and @melissawm (for example) wanted to co-author a re-org of the contributing/dev section, I would imagine you'd have support from the group. I guess a way to propose this would be to write an outline of the re-org (two levels or so deep), and propose a reasonable timeline, and then get buy in.
Anyway, that is just my suggestion for how to get larger documentation projects through - I'm sure there are other models.
story645 commentedon Jul 18, 2024
copying my next phase proposal from #28557 (comment)
rough plan for more clean up/polishing that should roughly close out the tasks above:
graph TD; A(is the issue) -->unresolvable-->C(explain why <br /> technically infeasible <br /> or not aligned with <br /> values/mission/scope/etc); A-->resolved--> B(explain why, <br /> link to docs, API, etc) ; A-->resolvable-->D(work w/ issue author <br /> on an implementable <br /> code/docs solution) A-->E(not sure)-->F(ask for more information) -->A;timhoffm commentedon May 1, 2026
@story645 much of this seems done. Is there still value in keeping this open?
story645 commentedon May 1, 2026
It possibly should have been a project, but I'm mostly keeping it open as a tracking issue of all my dev doc todos.