-
Notifications
You must be signed in to change notification settings - Fork 4.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Assort doc files into appropriate subfolders for easier navigation #79160
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Auto-requesting reviews from non-collaborators: @jbytheway
While I appreciate we barely have any C++ docs lumping them into compiling seems weird to me, I imagine peeps who find the compiling docs originally through github links would then outright ignore that folder once they're setup. (just renaming the folder to c++ would be fine imo) |
Summary
Infrastructure "The doc folder has been restructured for easier navigation"
Purpose of change
Making the docs easier to navigate, because they are a bit of a mess right now, and it's very hard to discover the file you want to read if you don't already know the filename.
Describe the solution
Have four distinct subfolders in doc/ directory:
compiling
c++
- for all things C++.JSON
- for all things JSON. Technical documentation on how to add content.design-balance-lore
- for design-level documentation on what content to add.user-guides
- for the few doc pages that we expose to the end-userMove the doc files into one of the four folders above, if appropriate
Grep codebase for
.md
string, and update the old links to point to new paths, when appropriate.Describe alternatives you've considered
code
for c++ andcontent
for JSON. But in the end I decided thatcontent
is a bit too ambiguous withdesign
, and I didn't want to create an extra folder level such ascontent/design/
vscontent/json_reference
because that felt unfair compared to a single level of C++.c++
anyway due to commentsTesting
Clicked around the docs in my branch on github - https://github.com/moxian/Cataclysm-DDA/tree/doc-shuffle . Seems to work but obviously was not able to check every link..
(I'm also hoping we have a CI check that'd yell at me if I missed something, but I'm not sure we do..)
Additional context
The former "Lore" folder was renamed to
design-balance-lore
because, turns out, it covered the design and balance aspects of the game pretty thoroughly, and was not focused exclusively on the narrative as the name would suggest.The problem I was originally trying to solve here is that it was invariably taking me way more time than neccessary to locate instructions on how to use astyle/clang-tidy/other things inside DEVELOPER_TOOLING.md to the point that by now I have memorized how to actually use them, but I would still struggle locating the docs. This stemmed from the fact that DEVELOPER_TOOLING.md is situated in the sea of completely unrelated json docs, and one needs to know the exact name beforehand in order to find it.
So I simply moved
DEVELOPER_TOOLING.md
closer to the compiler-related docs inCOMPILING/
. And then movedCODE_STYLE.md
there as well, because of course that's directly related (and if you're doing json changes you don't care about that one)But then the next logical step is to move json-related docs to the json-named folder... and design-related files design folder... and here we are...