8 ms·

To be fair, I'm not sure "offline readability" is an actual problem anymore. VS Code and (presumably) other IDEs offer a very simple live-preview window for vie

To be fair, I'm not sure "offline readability" is an actual problem anymore. VS Code and (presumably) other IDEs offer a very simple live-preview window for viewing and editing markdown files.

darknavi 5y ago
Assuming that those tools also implement the same set of MD functionality (like Mermaid)
armchairhacker 5y ago
We need to go back to something like Word documents. We’ve come full circle
- crabmusket 5y ago
  README.docx
  - seanw444 5y ago
    At least do LibreOffice format.
    - account42 5y ago
      README.pdf with interactive JS and 3D elements
      - seanw444 5y ago
        Now we're talking! Why read the documentation, when you can play the documentation?
  - dotancohen 5y ago
    If I ever see that in the wild, I'm going to escalate the arms race with a README.xml file.
- encryptluks2 5y ago
  How so? Word Documents are not made to be edited by hand. They are meant to be edited in Word. Markdown even with Mermaid is still readable and editable by hand. While I can agree Mermaid isn't my ideal markup, there are alternatives and you can even propose your own.
  - dotancohen 5y ago
    Mermaid is as readable as C++. The examples shown in the fine article are Hello, world. The information contained within would be just as clear in vulgar prose. However the Mermaid code to create complex flowcharts that are not easily described in words, would be just as opaque as the Netscape 5 codebase.
    - encryptluks2 5y ago
      I agree that it is no ideal, at least for my tastes, but I think what you are stating is an exaggeration. If you are using reference points like someone that knows little to nothing about technology, then just about anything different that what they are used is probably as readable as C++. For example, trying to read HTML would be the same to my grandma as trying to read C++.
      - dotancohen 5y ago
        The whole point of Markdown is "readable by humans" in unrendered form. Mermaid breaks that.
        encryptluks2 5y ago
        Readable by humans is relative. Mermaid does not make it unreadable to some humans. Again, you are free to create an alternative that makes it more readable. Some could say that adding tables to markdown makes it unreadable. There are lot of extensions for markdown that adds features, but you have to know what they are to read them and use them. Grandma doesn't have to use Mermaid if she doesn't want to.
_k9eq 5y ago
While it is true, these features seem to me to be added because Markdown is (ab)used the way it is. The issue is if you are working in an environment where it isn't possible, e.g. on a server where you only have vi/nano, and not even a TUI browser (or if you don't want to use an editor based on electron). My issue is that you can still have a nice readme (often even giving a better, brief overview) by sticking to HTML-free Markdown. Gitlab seems to be slightly better than Github, by allowing things like badges to be listed outside of the README, in the header of the repository page.
- toastal 5y ago
  > badges to be listed outside of the README This always irked me as I can't read the image when trying to look at raw text and the, say build status, isn't actually relevant to understanding the project. Sourcehut has an interesting approach where you can POST any HTML to an endpoint at it becomes the homepage. You can tag on extra markup if you want in the build step and that markup doesn't have to live in the README (say badges, other images, abbreviation tags, summary/details, etc.)
cerved 5y ago
My vanilla vim on ssh begs to differ. Offline readability matters
- WastingMyTime89 5y ago
  To you it does but manifestly your use case doesn’t matter to the people writing these pieces of software and these readme files. They care about their audience which want different things than you. At some point you can’t expect the world to cater for you. You have to deal with the annoyances which come with doing things differently or move on with your time.
  - cerved 5y ago
    the world runs on ssh terminals so I'd argue it does matter
junon 5y ago
Not everyone uses vscode
laumars 5y ago
Yes. The main use case I have for markdown is: * reading documents in the terminal (like man pages) * note taking In both those instances the less auto-formatting that the editor does the easier it is for me to use the use the file format. I’m sure you can say that editor auto-formatting isn’t an issue because people manage fine on MS Word. But the point is I want as little distractions as possible when not taking but I also want to be able to add headings and code snippets. So wrestling with an editor when it gets its formatting rules in a mess is the exact opposite of productively. Eg take a look at the number of authors that still use DOS editors for similar reasons.

To be fair, I'm not sure "offline readability" is an actual problem anymore. VS Code and (presumably) other IDEs offer a very simple live-preview window for viewing and editing markdown files.

darknavi 5y ago

Assuming that those tools also implement the same set of MD functionality (like Mermaid)

armchairhacker 5y ago

We need to go back to something like Word documents. We’ve come full circle

crabmusket 5y ago
README.docx
- seanw444 5y ago
  At least do LibreOffice format.
  - account42 5y ago
    README.pdf with interactive JS and 3D elements
    - seanw444 5y ago
      Now we're talking! Why read the documentation, when you can play the documentation?
- dotancohen 5y ago
  If I ever see that in the wild, I'm going to escalate the arms race with a README.xml file.
encryptluks2 5y ago
How so? Word Documents are not made to be edited by hand. They are meant to be edited in Word. Markdown even with Mermaid is still readable and editable by hand. While I can agree Mermaid isn't my ideal markup, there are alternatives and you can even propose your own.
- dotancohen 5y ago
  Mermaid is as readable as C++. The examples shown in the fine article are Hello, world. The information contained within would be just as clear in vulgar prose. However the Mermaid code to create complex flowcharts that are not easily described in words, would be just as opaque as the Netscape 5 codebase.
  - encryptluks2 5y ago
    I agree that it is no ideal, at least for my tastes, but I think what you are stating is an exaggeration. If you are using reference points like someone that knows little to nothing about technology, then just about anything different that what they are used is probably as readable as C++. For example, trying to read HTML would be the same to my grandma as trying to read C++.
    - dotancohen 5y ago
      The whole point of Markdown is "readable by humans" in unrendered form. Mermaid breaks that.
      - encryptluks2 5y ago
        Readable by humans is relative. Mermaid does not make it unreadable to some humans. Again, you are free to create an alternative that makes it more readable. Some could say that adding tables to markdown makes it unreadable. There are lot of extensions for markdown that adds features, but you have to know what they are to read them and use them. Grandma doesn't have to use Mermaid if she doesn't want to.

_k9eq 5y ago

While it is true, these features seem to me to be added because Markdown is (ab)used the way it is. The issue is if you are working in an environment where it isn't possible, e.g. on a server where you only have vi/nano, and not even a TUI browser (or if you don't want to use an editor based on electron). My issue is that you can still have a nice readme (often even giving a better, brief overview) by sticking to HTML-free Markdown. Gitlab seems to be slightly better than Github, by allowing things like badges to be listed outside of the README, in the header of the repository page.

toastal 5y ago
> badges to be listed outside of the README This always irked me as I can't read the image when trying to look at raw text and the, say build status, isn't actually relevant to understanding the project. Sourcehut has an interesting approach where you can POST any HTML to an endpoint at it becomes the homepage. You can tag on extra markup if you want in the build step and that markup doesn't have to live in the README (say badges, other images, abbreviation tags, summary/details, etc.)

cerved 5y ago

My vanilla vim on ssh begs to differ. Offline readability matters

WastingMyTime89 5y ago
To you it does but manifestly your use case doesn’t matter to the people writing these pieces of software and these readme files. They care about their audience which want different things than you. At some point you can’t expect the world to cater for you. You have to deal with the annoyances which come with doing things differently or move on with your time.
- cerved 5y ago
  the world runs on ssh terminals so I'd argue it does matter

junon 5y ago

Not everyone uses vscode

laumars 5y ago

Yes. The main use case I have for markdown is: * reading documents in the terminal (like man pages) * note taking In both those instances the less auto-formatting that the editor does the easier it is for me to use the use the file format. I’m sure you can say that editor auto-formatting isn’t an issue because people manage fine on MS Word. But the point is I want as little distractions as possible when not taking but I also want to be able to add headings and code snippets. So wrestling with an editor when it gets its formatting rules in a mess is the exact opposite of productively. Eg take a look at the number of authors that still use DOS editors for similar reasons.