2 ms·

> You probably want to compare RST vs. Markdown shrug You know what I mean You seem really hung up on cross-references as links, but I'm not that big a fan. I

> You probably want to compare RST vs. Markdown shrug You know what I mean You seem really hung up on cross-references as links, but I'm not that big a fan. In particular, Sphinx docs will cross-reference themselves a lot, which is super confusing to me; it makes me think "wait is there a more canonical reference than what I'm reading?", then I click it, then I'm back at the top of the page/section I was just on. Generally I prefer (fast, good) search, and Sphinx' isn't wonderful: it's basically `grep` for docs. I don't really need that, that's what `App site:textual.textualize.io` is for in DDG/Google. > I sure as hell am not going to force it on my users if I write e.g. a Rust crate-- I'd have to love rustdoc I mean, "have to love" is a contradiction. My point is that when you're a FOSS dev, you have to take any motivation you can get and avoid demotivations like the plague. Like in your case, I would assume you'd think twice about switching ecosystems from Python to Rust precisely because of your strong preference for Sphinx.

throwaway290 4y ago
> 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 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.
- camgunz 4y ago
  >> 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.
throwaway290 4y ago
> Sphinx is basically `grep` for docs. I don't really need that, that's what `App site:textual.textualize.io` is for in DDG/Google Let's do a study and compare Rich and Textual, which is based on Rich. Here's a Textual class: https://textual.textualize.io/reference/events/#textual.events.MouseCapture https://textual.textualize.io/reference/events/#textual.even.... I need to find what is MessageTarget, so after some futile ctrl-f'ing I copy-paste it into search field. Suggestions show barely related results, like a code listing and another unit that references MessageTarget. Hitting Enter just drops me not onto a search results page but onto a barely related page that does not document MessageTarget at all. Then I want to find out what Point is. I just go to Google for this. It shows me Geometry page, which seems related... Except it lands me at the top and do you know how many times "point" (and "pointer", "pointing", etc) are used on the page? Many times, which is why Google thinks it's probably the most related to Point. After a minute of ctrl-f'ing I find no docs for Point. Note that at this point I don't even know whether either MessageTarget or Point is documented at all. If they aren't, then what a great use of my time! Of course search engine doesn't have the slightest idea about what I need, it merely matches entered words. As you can see, search is the true grep for documentation that you are describing: dumb and barely useful by itself. Here's a Rich class: https://rich.readthedocs.io/en/latest/reference/console.html#rich.console.ConsoleOptions https://rich.readthedocs.io/en/latest/reference/console.html.... they didn't even describe each parameter, but if you want to find how to instantiate (and where to import from) a ConsoleDimensions it's one click away. Same for built-in types, thanks to Intersphinx (I guess when they stop relying on typing_extensions, Literal will be hyperlinked as well). RST nudges you towards explicitly denoting relationships between different parts of your documentation, because its default behavior is to treat a single backtick as a semantic identifier that signifies a particular unit, not just a random snippet of text. Whenever you use a backtick, it will warn you if you reference a nonexistent unit. Unlike dumb search, it actually knows what relates to what. If you think I diss the work creators put into the library--I don't, I'm just pointing out to you why cross-reference is useful, and I wrote my original comment about their decision of documentation builder since some of them are apparently on HN.
- camgunz 4y ago
  Hah well, I get what you're saying (I mean, I got it before this). It's not always easy to find what you're looking for in docs, and it sounds like you really look to cross-references to help you do that. My counterpoint here is the Google protocol buffers docs for Python [0]. Again I don't want to come down too hard on others' work, but just this front page isn't that helpful to me. For one, I don't need everything prefaced with `google.protobuf`, I know that's the package I'm looking at, and for another, the needless `google.protobuf` prefix and the attendant wrapping make the sections on the left really hard to scan. But let's get into a specific module: timestamp_pb2 [1]. There are a grand total of two cross-references that aren't to the Python docs (which are KeyError and bool, which like, not the most helpful of cross-references). That's not a great showing. If your argument here is that "RST nudges you towards explicitly denoting relationships between different parts of your documentation", I'm not seeing it, and I would guess these docs get a fair amount of traffic. --- My argument here is that you're seeing features in ReST, and extrapolating characteristics about ReST docs based on those features, while ignoring real-world considerations (like developer motivation, for one). I'm sure ReST has features that seem like they would encourage doc authors to use cross-referencing more. But the docs I use are barely cross-referenced, I use DDG/Google searches for this, and pragmatically I think this is the experience of most people. [0]: https://googleapis.dev/python/protobuf/latest/ https://googleapis.dev/python/protobuf/latest/ [1]: https://googleapis.dev/python/protobuf/latest/google/protobuf/timestamp_pb2.html https://googleapis.dev/python/protobuf/latest/google/protobu...

throwaway290 4y ago

> 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 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.

camgunz 4y ago
>> 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.

throwaway290 4y ago

> Sphinx is basically `grep` for docs. I don't really need that, that's what `App site:textual.textualize.io` is for in DDG/Google Let's do a study and compare Rich and Textual, which is based on Rich. Here's a Textual class: https://textual.textualize.io/reference/events/#textual.events.MouseCapture https://textual.textualize.io/reference/events/#textual.even.... I need to find what is MessageTarget, so after some futile ctrl-f'ing I copy-paste it into search field. Suggestions show barely related results, like a code listing and another unit that references MessageTarget. Hitting Enter just drops me not onto a search results page but onto a barely related page that does not document MessageTarget at all. Then I want to find out what Point is. I just go to Google for this. It shows me Geometry page, which seems related... Except it lands me at the top and do you know how many times "point" (and "pointer", "pointing", etc) are used on the page? Many times, which is why Google thinks it's probably the most related to Point. After a minute of ctrl-f'ing I find no docs for Point. Note that at this point I don't even know whether either MessageTarget or Point is documented at all. If they aren't, then what a great use of my time! Of course search engine doesn't have the slightest idea about what I need, it merely matches entered words. As you can see, search is the true grep for documentation that you are describing: dumb and barely useful by itself. Here's a Rich class: https://rich.readthedocs.io/en/latest/reference/console.html#rich.console.ConsoleOptions https://rich.readthedocs.io/en/latest/reference/console.html.... they didn't even describe each parameter, but if you want to find how to instantiate (and where to import from) a ConsoleDimensions it's one click away. Same for built-in types, thanks to Intersphinx (I guess when they stop relying on typing_extensions, Literal will be hyperlinked as well). RST nudges you towards explicitly denoting relationships between different parts of your documentation, because its default behavior is to treat a single backtick as a semantic identifier that signifies a particular unit, not just a random snippet of text. Whenever you use a backtick, it will warn you if you reference a nonexistent unit. Unlike dumb search, it actually knows what relates to what. If you think I diss the work creators put into the library--I don't, I'm just pointing out to you why cross-reference is useful, and I wrote my original comment about their decision of documentation builder since some of them are apparently on HN.

camgunz 4y ago
Hah well, I get what you're saying (I mean, I got it before this). It's not always easy to find what you're looking for in docs, and it sounds like you really look to cross-references to help you do that. My counterpoint here is the Google protocol buffers docs for Python [0]. Again I don't want to come down too hard on others' work, but just this front page isn't that helpful to me. For one, I don't need everything prefaced with `google.protobuf`, I know that's the package I'm looking at, and for another, the needless `google.protobuf` prefix and the attendant wrapping make the sections on the left really hard to scan. But let's get into a specific module: timestamp_pb2 [1]. There are a grand total of two cross-references that aren't to the Python docs (which are KeyError and bool, which like, not the most helpful of cross-references). That's not a great showing. If your argument here is that "RST nudges you towards explicitly denoting relationships between different parts of your documentation", I'm not seeing it, and I would guess these docs get a fair amount of traffic. --- My argument here is that you're seeing features in ReST, and extrapolating characteristics about ReST docs based on those features, while ignoring real-world considerations (like developer motivation, for one). I'm sure ReST has features that seem like they would encourage doc authors to use cross-referencing more. But the docs I use are barely cross-referenced, I use DDG/Google searches for this, and pragmatically I think this is the experience of most people. [0]: https://googleapis.dev/python/protobuf/latest/ https://googleapis.dev/python/protobuf/latest/ [1]: https://googleapis.dev/python/protobuf/latest/google/protobuf/timestamp_pb2.html https://googleapis.dev/python/protobuf/latest/google/protobu...