51–56 of 56 posts
So you download a folder or a zip file (anyone remember PKZIP?) and try to determine what its purpose or "application" is. I mean, there is almost certainly an app in here, right?
So, why have I downloaded this .zip file? Not sure, had an interesting title, and yeah, let's see what the author has to say. First stop: README.txt
Earlier quoted context omitted.
I think markdown reads very nicely in text form. Title === Summary of the page # H1 Intersting Topic The most important part of [1] is... ## H2 What others say > Quote from somebody. Callout something. And then it's implemented like: ``` // this code is a demonstration of how to query foo func foo() { does_thing(); } ``` # Conclusion You should use markdown to structure your documents. [1]: https://example.com
I said yes, you can read it. But I also noted that it's riddled with ## and other junk that doesn't do anything beneficial because you're seeing plain text. So why have detracting, non-informational characters in there?
I'd argue in favor of those. A competent text editor (let's say no older than 40 years old) can highlight and/or render that. When using base markdown, those things add structure to the document. I'd much rather see a markdown file with basics like headers and code sections (which are usually highlighted correctly) than a raw .txt file.
however I think your argument goes doubly hard when dealing with these more advanced html integrated readmes. The md file of the example readme is not well readable when opened in a text file to me- and there's actually very little content there! I prefer a more minimal approach where opening the .md file gives me the information I need, and opening it in a rendered environment gets me some niceties (perhaps you've got badges with coverage or versions nrs idk). But it should work in both.
Earlier quoted context omitted.
I think markdown reads very nicely in text form. Title === Summary of the page # H1 Intersting Topic The most important part of [1] is... ## H2 What others say > Quote from somebody. Callout something. And then it's implemented like: ``` // this code is a demonstration of how to query foo func foo() { does_thing(); } ``` # Conclusion You should use markdown to structure your documents. [1]: https://example.com
I said yes, you can read it. But I also noted that it's riddled with ## and other junk that doesn't do anything beneficial because you're seeing plain text. So why have detracting, non-informational characters in there?
> https://github.com/appsmithorg/appsmith That is more of a GitHub landing page than a readme. > An effective README file needs to tell your audience what your project does, how to use it, and how they can help out. The readme starts with an `a` image tag nested within a `p`.
Yep, the author of their readme is more interested in marketing their product than explaining how to get started using the project. It's honestly like the product person wrote the readme and not the engineers. And I consider that to be a pretty big red flag. At least, I'm not using the project any time soon because it's wasted my valuable time marketing to me instead to getting me straight to into the software. And i…
Earlier quoted context omitted.
Yep, the author of their readme is more interested in marketing their product than explaining how to get started using the project. It's honestly like the product person wrote the readme and not the engineers. And I consider that to be a pretty big red flag. At least, I'm not using the project any time soon because it's wasted my valuable time marketing to me instead to getting me straight to into the software. And i…
Putting a tracking pixel in a readme is a new one, wow. I would never want to clone that project in case I accidentally open the readme
Earlier quoted context omitted.
I said yes, you can read it. But I also noted that it's riddled with ## and other junk that doesn't do anything beneficial because you're seeing plain text. So why have detracting, non-informational characters in there?
> riddled with ## and other junk I'd argue in favor of those. A competent text editor (let's say no older than 40 years old) can highlight and/or render that. When using base markdown, those things add structure to the document. I'd much rather see a markdown file with basics like headers and code sections (which are usually highlighted correctly) than a raw .txt file. however I think your argument goes doubly hard w…
But I'm not EDITING them. I just want to double-click on it and read the document, rendered properly. I do not want to have to open it in an editing environment and then invoke a preview (which often takes double the screen space). Again, WTF is up with the lack of lightweight, dedicated Markdown viewers?
I don't agree that stuff like ## and `` all over the place is eye-catching and attractive formatting. It's absurdly regressive. At that point, why not just use RTF, for which there are built-in viewers in the dominant OSes? Or if you really want plain text, use indentation, spacing, and capitals to organize the document.
If OSes' default viewers (like Notepad in Windows or Preview on the Mac) would render Markdown, I'd be fine with it. But they don't, and if they haven't added it yet, it doesn't seem that they will.