I got criticized in one of my post why I put a documentation for the app inside its doc directory instead of putting Rust documentation there. So, I would like to get a wider opinion if I do something wrong.
Rust doc has a very neat feature allowing to merge documentation for projects or/and crates in one integrated HTML doc system. In this case, I do not need to switch from one documentation for some crate to another documentation for another crate, because all my crates already transparently integrated. It gives me a possibility to use a doc directory inside a project to document functionality of the application itself not related to Rust. Say more, users of my app even have no idea that Rust was used for programming the app. They can think that C or some other language as Go was used.
Do I do right, or you would suggest a different approach?
The only intent I had is that that when you use the term "docs" without further context on a Rust forum, the assumption is going to be rustdocs, eg. the output of "rust doc" that's rendered on docs.rs, and has no connection to a docs directory. Specifically, there's no statement about anything you might be doing with a docs directory!
If there's any criticism, it's only that you should try to keep in mind what other people know and will assume, but it's a very weak criticism given how difficult that is known to be.
Awesome, my AI agent tells me same sentence again and again. Any AI system requires a context it can start digging and then produce answers upon it. Why my posts frequently miss the context? It's a simple human test - prove that you are a human before trying to answer. But I can't agree more that we all are tired constantly prove that we are human. So no problem, if you or I feel that we do not have enough context to answer, just skip answering. Although nobody prevents you from deep digging in the context.
The project contains doc directory. A purpose of the directory to keep information on the project itself, not for the project Rust implementation. However, the project has Rust documentation too, it's defined in the build script.
... huh? The context in that thread was you replying to someone else mentioning include being used for docs, then you saying... something about it making hard to keep things in sync, me clarifying the specifics of about the earlier comment you were replying to, then you clarifying about you using it for your help text, me replying ah, we were talking past each other.
I was perfectly happy to let that be that we were just talking about different things.... and now I'm being accused of respectively saying you're doing the wrong thing (I didn't), not "understanding the context" by managing to somehow intuit what you meant by
Is that by "keep doc in a separate file" you meant "having two copies of the same documentation" and not "having documentation for an API in a separate file to the thing being documented" which is the entire point of rustdocs and why I therefore talked about rustdocs in my reply to that, and then clarified at the end that we were talking about different things, which wasn't a problem until you somehow misunderstood that post and created this thread.
Look, communicating in writing is hard, saying that the fault lies in the other person for not understanding you doesn't help any more than saying the fault lies in the person not explaining correctly - the only reason I mentioned it above is because I was trying to point out that that is the only criticism you could of you in that statement.
So, in summary:
No, nobody is saying you can't put documentation in a docs directory. Nobody was criticizing you in any meaningful way (even the don't do that replies on that thread are "there's easier and better options" not "you shouldn't do that")
Yes, it's the major problem when people can't understand each other, and a source of the problem, because they think differently. And sure I apologize if I ever said you can't express yourself clearly. It's hard to understand you for me, but I do my best, trust me. Regarding criticism, again, I like it, because it makes my mind much clearer than it was before. It's why I like your responses. Please do not stop arguing.