4 ms·

I personally have found there is something of an art to a good readme. So folks can make one that is informative and visual, others can't. I have a project or t

by pard68 3y ago

I personally have found there is something of an art to a good readme. So folks can make one that is informative and visual, others can't. I have a project or two that suffered because my readme designing skills suck, then talented friend PR'd a great readme with screenshots and such.

andai 3y ago
It may be an art, but I wouldn't say it takes much talent to include a screenshot, GIF or YouTube link! Most likely he just didn't give it much thought.
- Retr0id 3y ago
  Speaking only for myself, often a project is in a half-finished state, and any provided screenshot would quickly become out of date.
  - dharmab 3y ago
    Your audiences imagination is probably even worse!
  - beezlewax 3y ago
    You could probably automate a tool to take screenshot for you.
    - yowzadave 3y ago
      This sounds like a slippery slope into yak-shaving…next thing you’ll open source your automated screen-shorting tool, and it will require a readme of its own!
      - pard68 3y ago
        Should I write a new screenshot tool for the screenshot tool's readme?
    - candrewlee14 3y ago
      Sounds something like charm’s vhs: https://github.com/charmbracelet/vhs https://github.com/charmbracelet/vhs
- Nition 3y ago
  Weirdly even commercial software websites seem to do this a lot. Pages of text and some mostly-unrelated images with no screenshots at all. Sometimes you can learn more about a program from screenshots of it in Google Images than from the official website.
  - nineteen999 3y ago
    Agree totally - I want to see whether the controls for what I want to use the software for are in prominent positions, buried deep in some menu, or completely non-existent. I also want to see what other UI fluff is crowding out those controls and becoming distracting for me and my users, and how bloated the application is around other tasks that I have no use for. It's not the sole way to evaluate usefulness of software obviously, but it can help save a lot of time if it's clear from screenshots or videos if its not a good fit for my needs.
    - Nition 3y ago
      Honestly half the time the site doesn't even describe what the software is for. They'll be like "CRE8TR TAKES CREATIVITY TO A NEW LEVEL", "Used by industry professionals worldwide!" If you've just come from a random link on Hacker News or something they can be incredibly vague. Once again, a screenshot immediately shows me "oh, it's a UI wireframing tool."
Yondle 3y ago
Your are absolutely a software engineer. Counter point for counter point sake.

by pard68 3y ago

andai 3y ago

It may be an art, but I wouldn't say it takes much talent to include a screenshot, GIF or YouTube link! Most likely he just didn't give it much thought.

Retr0id 3y ago
Speaking only for myself, often a project is in a half-finished state, and any provided screenshot would quickly become out of date.
- dharmab 3y ago
  Your audiences imagination is probably even worse!
- beezlewax 3y ago
  You could probably automate a tool to take screenshot for you.
  - yowzadave 3y ago
    This sounds like a slippery slope into yak-shaving…next thing you’ll open source your automated screen-shorting tool, and it will require a readme of its own!
    - pard68 3y ago
      Should I write a new screenshot tool for the screenshot tool's readme?
  - candrewlee14 3y ago
    Sounds something like charm’s vhs: https://github.com/charmbracelet/vhs https://github.com/charmbracelet/vhs
Nition 3y ago
Weirdly even commercial software websites seem to do this a lot. Pages of text and some mostly-unrelated images with no screenshots at all. Sometimes you can learn more about a program from screenshots of it in Google Images than from the official website.
- nineteen999 3y ago
  Agree totally - I want to see whether the controls for what I want to use the software for are in prominent positions, buried deep in some menu, or completely non-existent. I also want to see what other UI fluff is crowding out those controls and becoming distracting for me and my users, and how bloated the application is around other tasks that I have no use for. It's not the sole way to evaluate usefulness of software obviously, but it can help save a lot of time if it's clear from screenshots or videos if its not a good fit for my needs.
  - Nition 3y ago
    Honestly half the time the site doesn't even describe what the software is for. They'll be like "CRE8TR TAKES CREATIVITY TO A NEW LEVEL", "Used by industry professionals worldwide!" If you've just come from a random link on Hacker News or something they can be incredibly vague. Once again, a screenshot immediately shows me "oh, it's a UI wireframing tool."

Yondle 3y ago

Your are absolutely a software engineer. Counter point for counter point sake.