Creating a developer and a user subdirectory in docs
michaelfolkson opened this issue · comments
We need to bring a subdirectory structure to the docs directory. As suggested by @MarcoFalke and @ryanofsky in #23154 it is easier to assess the quality of a doc when you know who it is targeted towards e.g. developer or user. And there is a long list of documents in the docs directory that ideally we would bring some structure to.
(There has been previous discussion of improving the docs in #20132. @MarcoFalke has opened a PR to add a developer (devel) subdirectory in #23528 that is currently getting review.
Which subdirectory (developer or user or neither ie stay in the docs directory and not be placed in a subdirectory) existing documents should go into. If there is disagreement on which subdirectory the existing doc should go into I propose to put in neither. This is my guess of where they should go but please let me know if you disagree.
JSON-RPC-interface.md user
README.md neither
README_doxygen.md neither
README_windows.txt neither
REST-interface.md user
assets-attribution.md neither
assumeutxo.md developer
benchmarking.md developer
bips.md developer
bitcoin-conf.md user
bitcoin_logo_doxygen.png neither
build-android.md user
build-freebsd.md user
build-netbsd.md user
build-openbsd.md user
build-osx.md user
build-unix.md user
build-windows.md user
dependencies.md user
descriptors.md user
developer-notes.md developer
dnsseed-policy.md user
external-signer.md user
files.md neither
fuzzing.md developer
guix.md user
i2p.md user
init.md developer
managing-wallets.md user
multiprocess.md developer
productivity.md developer
psbt.md user
reduce-memory.md user
reduce-traffic.md user
release-notes.md neither
release-process.md neither
shared-libraries.md developer
tor.md user
tracing.md developer
translation_process.md user
translation_strings_policy.md user
zmq.md user
Putting my nits for #23528 here so feel free to ignore.
- I would prefer
developeras the subdirectory name todevel. I have never seen that shortening anywhere before.- I think filenames shouldn't be changed. In doc: Move internal dev docs to doc/devel/ #23528 developer-notes.md is renamed dev-notes.md for zero upside imo.
Agree on both
shiza also preferred as a nit to keep the filename developer-notes.md (IRC)
Not sure if it makes sense to create a user directory. This will break external links and I expect user docs to be linked more than internal dev docs.
Is there a reason for a user dir?
Is there a reason for a user dir?
Ah ok, fair enough. So we'll assume the files that don't make it into the developer subdirectory are user docs? Definitely fine with that, we can possibly state that explicitly in the doc README at a later point. I'm referring to the discussion in #23154 where you suggested (rightly in my view) that when someone drafts a doc they should be clear on whether it is targeted towards developers or users. The assumption would be that if you don't put it in the developer subdirectory it is targeted towards users.
More nits for #23528, feel free to ignore.
I'd personally put bips.md, shared_libraries.md, tracing.md and zmq.md in developer directory too but that can be done in a future PR (if it should be done at all, kinda up to the primary doc contact)
I think those are for external developers (aka users).
Oh ok, interesting. So we are defining users as "non-developers and external developers"? And we are defining developers as "internal developers"? Ok, good to know. The definitions in my head were different.
@ryanofsky from #23528 (comment):
Just IMO, but I think "doc/design" and "doc/contributing/" folders would be more helpful than a "doc/developer/" folder. "Design" folder would hold files like assumeutxo.md, fuzzing.md, multiprocess.md, translation_process.md that tell you about the design and implementation of cross-cutting features in existing code, and can go into the weeds of how things work technically. "Contributing" folder would hold files like translation_policy.md, developer-notes, release-process, which should be less technical and just tell you how to do whatever task you're trying to do.
Some of our current documents are a little jumbled and might need to be split up to fit this schema perfectly. But I think even just moving current documents to "doc/design" and "doc/contributing/" folders with no changes would be an improvement to at least give each document a clear purpose.
By comparison, I think adding "doc/developer/" folder could be a step backwards and ingrain bad habits of producing documentation without a clear focus. (I will also admit I have kind of a negative reaction to the word "developer". I feel like if I am looking at a github doc directory, than yes I am a developer. Stop asking me who I am and tell me where to find the information I need.)
But if other people like doc/developer/ it SGTM. Just wanted to suggest an alternative.
@ryanofsky: That sounds like a further separation of the developer directory to me into design and contributing subdirectories. I don't have a strong view.
I will also admit I have kind of a negative reaction to the word "developer". I feel like if I am looking at a github doc directory, than yes I am a developer. Stop asking me who I am and tell me where to find the information I need.)
I disagree that anyone looking at GitHub is a developer interested in the code. There are docs here that are focused towards users of Core that don't need to be developers interested in how the code works. And GitHub today as a site certainly caters for people who don't use the command line let alone examine the code.
@ryanofsky: That sounds like a further separation of the developer directory to me into design and contributing subdirectories. I don't have a strong view.
Yes, the idea is if you are trying to understand code you would not look in the same place for rules for contributing. If you are trying to contribute, you just need to know what ruleinformations to follow and not an in-depth technical discussion.
I will also admit I have kind of a negative reaction to the word "developer". I feel like if I am looking at a github doc directory, than yes I am a developer. Stop asking me who I am and tell me where to find the information I need.)
I disagree that anyone looking at GitHub is a developer interested in the code.
Sorry, this a tangent, my main point is before this. But this is not what I'm saying or assuming. I'm just saying if I am using github, and I am exploring or looking for information, I think asking me to think about whether I am a "developer" or is irritating, and doesn't tell me whether there's technical information in the folder or just a bunch of rules. If other people think walling off "developer" information helpful, then great. I would prefer to organize things topically. Tell me what's in the folder. Don't ask me who I am.
why not make the document separation a thing around how to get started and what next you should look at than having to segregate it via dev and non-dev. It should be pretty much a pointer.
to improve on what @ryanofsky said.
we can have it like
`
doc/getting _started/
- installation.md
...
`
so instead of being fussy it can be a navigator instead.
@jonatack from #23528 (comment)
I wonder to what extent the current state causes confusion.
As one data point, this change would break more than a dozen links in the articles on my website, as well as another dozen links in https://github.com/jonatack/bitcoin-development.
These links would require not only updating but perhaps also adding explanatory notes in each file or post about which links are relevant before and after v23.
@jonatack: I'm not seeing why updating these links would be a problem for you other than presenting a one-off task for you to update the links in your repo? The rationale for doing this is not just confusion, it is for making it clear who the document is targeted towards and hence demanding a better standard of documentation. We already have a long list of docs (which will continue to increase over time) with no directory structure or organization and no clarity on who the documents are targeted towards.
In addition I'd like to bring some of your docs into this repo (in a developer directory or equivalent) as I think they are better than what is currently in this repo. If we do that we can link to this repo rather your personal repo and then you don't have to take the load of continuously updating them.
#23528 has been closed. I'm not interested in picking this up either as I think very few care and those that do would rather keep the status quo if they can't have their exact personal preference. Thanks for the attempt though @MarcoFalke.