>> shrug You know what I mean > Confusing file formats and documentation builders, but more importantly shrugging off miscommunication, makes me think you don'

>> shrug You know what I mean > 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.