Along with CONTRIBUTING.md, I've been including a WRITING.md in my projects, too. Is it bulletproof? No. But it does help things like READMEs, PR descriptions, and other documentation to be much more readable than your garden variety slop. Enough so that further editing is usually pretty painless.
Would you mind sharing a link? It’s ok if you don’t want to. This is just something I feel like I’ve been really struggling with and would love to see how others are trying to tackle it.
I'm not the original commenter you replied to, but I have thoughts that might be relevant. These things are quite subjective so some people will disagree that this is a good example, or with what I'm about to say so have a punch of salt at the ready…
I think "pretty average" is the thing to strive for in a README. The right balance of detailed but concise, not overly festooned with unnecessary verbiage like a stereotypical recipe page, a simple "what is it", "key features", "how to get/install", "more detail on features / example use" structure.
Of course it gets harder to find that balance as the size and scope of a project expands, you have to become judicious with cutting things out and excising them to extended documentation instead of everything being in the README. For a thing this size everything is close to the right balance if you word+arrange it right.
If this one is AI written (there are signs, but those are things humans have long done which is why AIs copy them) it has been human edited rather than just thrown up as-is.
> If you are struggling a lot with that, perhaps you are overthinking it or trying to shoehorn in too much detail?
The opposite problem to be honest. I maintain pretty complex projects so lean towards leaving most stuff out and linking to documentation outside the readme. But I frequently get accused of underselling the project.
But you’re right that I might be over thinking things.
After reading the first sentence, I cannot stop imagining some Rust people cannot stop salivating at the prospect to a version saying, "written in Rust", "safe", etc. ~
Not really. One example image has Capella, Rigel, and Sirius clearly marked. But even with that, I can not make out Orion, probably the most recognizable constellation behind the big dipper.
I would absolutely love a terminal Stellarium alternative, but this isn't it.
Not as-is, looking at the options list there seems to be no way to ask it to output one frame then exit. That would presumably be an easy option to add.
Well done, any plans to show other space objects too? Like the ISS or Starlink? One thing I ran into when tracking satellites in the browser: CelesTrak's TLE files skip satellites with six-digit catalog numbers, which is most of what's been launched lately, so new Starlinks just weren't there. Their CSV files have them tho.
The screensaver idea is pretty cool. Have it show the sky where you live and label a few bright stars or planets. Then when you step outside, you've actually got something to look for.
29 comments
[ 1.2 ms ] story [ 35.4 ms ] threadI took note of your suggestion, next time I will write the README in the voice of da-luce/astroterm README.
(Curious as someone who struggles to write readmes)
I think "pretty average" is the thing to strive for in a README. The right balance of detailed but concise, not overly festooned with unnecessary verbiage like a stereotypical recipe page, a simple "what is it", "key features", "how to get/install", "more detail on features / example use" structure.
Of course it gets harder to find that balance as the size and scope of a project expands, you have to become judicious with cutting things out and excising them to extended documentation instead of everything being in the README. For a thing this size everything is close to the right balance if you word+arrange it right.
If this one is AI written (there are signs, but those are things humans have long done which is why AIs copy them) it has been human edited rather than just thrown up as-is.
The opposite problem to be honest. I maintain pretty complex projects so lean towards leaving most stuff out and linking to documentation outside the readme. But I frequently get accused of underselling the project.
But you’re right that I might be over thinking things.
After reading the first sentence, I cannot stop imagining some Rust people cannot stop salivating at the prospect to a version saying, "written in Rust", "safe", etc. ~
I would absolutely love a terminal Stellarium alternative, but this isn't it.
Having stars and planets at your fingertips...
[0] https://www.casio.com/us/watches/50th/Heritage/1980s/
https://www.acme.com/software/phoon/
`brew install phoon`
astroterm -cub --city=Seattle -t 2 -l 2