Confusing file formats and documentation builders, but more importantly shrugging off miscommunication, makes me think you don't care much about documentation despite how much of it you wrote. Your position is thus unsurprising but also unlikely to inform my position (like I know it'd be pointless to argue about using static typing and running typecheckers with someone who sees ensuring code correctness as a chore).
> it makes me think "wait is there a more canonical reference than what I'm reading?"
Respect the user. If user lands on a doc section you don't know whether the user previously read everything else. You want to err on the side of more links, hitting a link and going back is quick but having to search is a major waste of time especially not knowing whether there is anything to be found in the first place. (This in particular applies to references, less so for tutorials that are intended to be read in order than jumped around.)
> I would assume you'd think twice about switching ecosystems from Python to Rust precisely because of your strong preference for Sphinx.
If I think Rust is the right tool and I want to work with Rust then I will use Rust. Documentation conventions are not much of a factor, they come with the territory, I don't see it as a demotivating chore or as a choice. Write language X? Use documentation system Y. Learn it and be satisfied with the end result.
If we are really talking about the least challenging ways to write docs then for me might be a Google Doc, should I do it? Of course I know it's bad, unsemantic, inconvenient to read and cross-link and generally completely wrong for the ecosystem so I can't possibly be motivated.
> Confusing file formats and documentation builders, but more importantly shrugging off miscommunication, makes me think you don't care much about documentation
Sorry what I meant here is what I wrote: you knew I meant ReST, and any further discussion was a waste of time. I think you're trying to weirdly score points here by pedantically insisting that there's a meaningful difference between Sphinx and ReST in the context of our conversation, but there isn't, and there's obviously no miscommunication.
I do care about documentation, but in a pragmatic sense. I've written a lot of it--primarily in Sphinx (I'm gonna keep doing this to you) and doxygen--but I've read a lot more, and as a result I'm pretty sensitive to the experience of users.
>> [Sphinx' relentless cross-referencing is confusing to me]
> Respect the user.
This is a good example. I brought up this issue I have with Sphinx as a user, and you dismissed my user experience by telling me to... respect myself? Maybe you think it's a good idea to err on the side of more links. Maybe I think it's a good idea to rely on high-level organizations and search. I don't know that there's an absolute good here. But it's worth saying that not even Wikipedia links everything it possibly can. That tracks with my experience where I find too many links to be noisy.
> Documentation conventions are not much of a factor, they come with the territory, I don't see it as a demotivating chore or as a choice. Write language X? Use documentation system Y. Learn it and be satisfied with the end result.
This seems contradictory with:
> If we are really talking about the least challenging ways to write docs then for me might be a Google Doc, should I do it? Of course I know it's bad, unsemantic, inconvenient to read and cross-link and generally completely wrong for the ecosystem so I can't possibly be motivated.
And this is exactly what I'm saying haha. I don't know why you're being so oppositional. You have strong opinions about documentation systems. If some ecosystem's default was "unsemantic, inconvenient to read and cross-link", you're saying you wouldn't be motivated. Great, then we agree! I think FOSS devs should be free to choose their own doc systems based on what motivates them too.
Confusing file formats and documentation builders, but more importantly shrugging off miscommunication, makes me think you don't care much about documentation despite how much of it you wrote. Your position is thus unsurprising but also unlikely to inform my position (like I know it'd be pointless to argue about using static typing and running typecheckers with someone who sees ensuring code correctness as a chore).
> it makes me think "wait is there a more canonical reference than what I'm reading?"
Respect the user. If user lands on a doc section you don't know whether the user previously read everything else. You want to err on the side of more links, hitting a link and going back is quick but having to search is a major waste of time especially not knowing whether there is anything to be found in the first place. (This in particular applies to references, less so for tutorials that are intended to be read in order than jumped around.)
> I would assume you'd think twice about switching ecosystems from Python to Rust precisely because of your strong preference for Sphinx.
If I think Rust is the right tool and I want to work with Rust then I will use Rust. Documentation conventions are not much of a factor, they come with the territory, I don't see it as a demotivating chore or as a choice. Write language X? Use documentation system Y. Learn it and be satisfied with the end result.
If we are really talking about the least challenging ways to write docs then for me might be a Google Doc, should I do it? Of course I know it's bad, unsemantic, inconvenient to read and cross-link and generally completely wrong for the ecosystem so I can't possibly be motivated.