Readme.so – Easiest Way to Create a Readme
readme.so
readme.so
However, based on how she talks about readme.so on Twitter and the fact that it's free and open source, it's clear she built it just to build something cool.
If she's open to a job, then she gets to continue working on something called ReadMe that's in a similar vein! If she's not, for whatever reason, then there's no harm done and I hope she takes my comment as a compliment :)
1. Linking other pages is buggy. Sometimes Readme autocompletes the page name and sometimes it doesn't. In general, the UI feels a little buggy and that's a big issue given that it's the entire reason I'm using your product.
2. I couldn't figure out how to make my docs publically available during the trial. I still don't know if this is because actually making your docs public is a paid feature or if I couldn't find the right button.
3. I desperately needed an export to pdf and that wasn't available during the trial despite the promise on the home page that the trial includes all features.
4. My cofounder thought the price was a little high given how easily we could handle docs ourselves.
There were some things I really liked:
1. I love the way you can embed API keys in the docs based on the reader's identify.
2. The API related features also look cool, although they aren't relevant for us.
Lastly, I'm not a customer in the end but one feature that I would have paid for (at the time when I was still evaluating this) is the ability to password protect docs and allow access only to specific people you invite. (Not paid users on your own team though. Just people you invite as readers.) We're still mostly in stealth mode but we do have prospects trying out our software regularly and would like to send them a nonpublic version of the docs that they can see. (Hence my desire to export to pdf, but private docs would be better than pdf.)
I only write readme's maybe once every few months or perhaps once a year, and having a template (interactive like this one, or otherwise) that someone else has thought about is super useful to me.
I actually do create a few README files every month (cos of Microservices), but I still don't understand why someone would use a tool to generate README files.
But to have something like this open along with that template would be really cool (and probably a resource hog to the editor/IDE, heh!)
Notion went down a few months ago due to issues with their .so domain and they said they're planning to move.
So now I'm the proud owner of "goliath32.com", which I currently keep parked until I finally, hopefully get around to overhauling my 10 year old personal site.
EDIT: some context that is probably relevant to this topic that I should not presume to be familiar with everyone is the controversy surrounding .io domains:
https://gigaom.com/2014/06/30/the-dark-side-of-io-how-the-u-...
The .so NIC "adjusted" the price IIRC around 2014 or so.
Most of the domains I have, or ever had, cost somewhere < 20 Euro per year. Whether this is a reasonable price for occupying less than 100 bytes in someones database (among tons of others, paying for that privilege) is debatable, but is IMO ok-ish.
When it gets closer to Euro 100,- per year (IIRC!) it does start to get painful and I start thinking if that is really worth paying out of my own pocket for my spare time stuff that people nowadays may not even look at at all. At that point I start thinking "I'd rather have a tilde-directory some place and eat a couple Pizzas a year for the money instead".
I migrated that stuff to goliath32.com and, after I simply ran out of time/enthusiasm to maintain a blog, I eventually decided to split the software projects up to a separate, more professional looking place, under "infraroot.at" (a TLD in the country where I live). As I said, I still want to get my act together on the personal stuff and eventually bring the goliath32.com back to live, which I have currently shelved since the interesting stuff was moved elsewhere.
Politics and country matters are something to keep in mind, of course, when you get yourself a fancy two-letter TLD (thanks for pointing out the .io controversy), but please don't try to spin a glorified database entry for which I'm not willing to pay for through my nose into some kind of ad-hominem attack.
I'm not running some kind of startup. Outside my work I'm just some guy tinkering with electronics, software and network stuff, and sometimes I write about it on the Web, so naturally I would like to have a catchy domain name with my IRC and IRL nick name in it that people know my by. I went with the .so domain, because it made for a nice play on words, same for the .com domain. Why do I have to justify that all of the sudden?
> or you can use a domain in your home country.
For some of my more involved software projects, that's exactly what I did. It says so right in the post you replied to.
Describing these events the way you do makes it sound as if you're being blackmailed or something. You're not. The Somalian government have the right to handle the .so domains however they please. If they demand that people are either Somali or otherwise pay a fee of 80 euros, there is nothing inherently wrong with that. If you find that an unreasonable price, go elsewhere. Nobody is forcing you to buy the domain. Which, as far as I can tell, is what you did.
Basically, what I don't understand is why you describe the event in a way that makes it sound as if they denied you something that you were entitled to when that was not the case.
I get that (I went to to high school). And I don't have any objections here.
When you buy a fancy ccTLD from a foreign country, you are [most likely] dealing with a government, not a businesses. It is their perfect right to decide that their citizens should be prioritized. They increase the fees 4-fould for anyone without a citizenship to incentivize them to go elsewhere.
When you buy a fancy ccTLD from a foreign country, that's a risk you take and something you should be aware off. That's my whole point.
From my perspective the following happened: I did take that risk. One day, my domain hoster told me to either send them a copy of my Somalian pass port, or I'd have to pay more. So at first I thought, I'll just pony up some more cash then. I already thought that domain prices are mostly fictional, given what I'm really paying for, but then I got a bill that made me go "Smoley Hokes! Now that's a lot of money for a domain name!". I didn't react like you and divided it by 12, rather I started comparing the price tag to other things I would much rather buy for that money, then I started multiplying it, because it's per year and quickly realized that that's just a lower bound, since I have no guarantee, that there isn't another price increase in 2 years or so. So I thought "Well, it's just a personal website, I'll get a domain somewhere else then, better be safe and use a non ccTLD". Even now, if I divide it by 12, I'd still rather buy my favorite take away menu at the Vietnamese place across the street once a month for 6.90.
The registrar giveth and the registrar taketh away. There were no demands made, no tears shed, no curses uttered and no fists shaken. What it boiled down to on my side was a couple minutes of getting a fresh drink, thinking up a new domain name that made me chuckle a little and hacking away.
Seeing a link to a .so domain on HN a couple years later made me remember the whole story and peeked my curiosity. And sure enough, there was a commend devoted to the domain. I chimed in, posting a very brief description of my personal anecdote. I added an extra line, pointing out the new, domain name I got as a replacement, thinking someone might appreciate the joke (it got a few laughs last time I mentioned it, but to be fair, everyone involved was already slightly intoxicated). In my original comment I made no allegations against anyone. I did not discuss the motivations of any of the parties involved (including my own), or local politics in Somalia or any of the socioeconomic implications of this story. I tried to point out, using a personal annecdote, why buying a fancy, foreign ccTLD might be problematic, as a remark on a question asked, foolishly assuming that most of this should be clear and it would be enough to just provide the key details of my story.
I'm sorry if I picked the wrong words or something that have some weird semantics or implications that I wasn't aware of (not being a native English speaker and all), but I have the feeling that I'm suddenly in a situation where I have words put in my mouth and fingers pointed at me, being framed as a freeloading baddie, based on things I never intended to say. That made me slightly annoyed, so sorry if my earlier response was a little harsh.
// Goliath
> Some years back, I used to be the proud owner of "libgoliath.so", but then they suddenly decided to hike the price to IIRC Euro 80,- per year (either that, or prove that I have a Somalian citicenship). So I dropped that.
I don't see any entitlement here at all, just a person calling a ripoff a ripoff.
Documentation is not our strong suit and I was wondering where to start with a good template that has some level of... professionalism / proven.
I was so excited I made a video about it and shared my thoughts on why and how GitHub should integrate this. https://youtu.be/kfOimInsnr4
One of my struggles at work has been inheriting some code base from whichever team that has no documentation or it’s not even clear why something was built in the first place. Sometimes we’re left scratching our heads — “how do I even build this thing?”
I’m a strong believer in a concise Readme file.
After having to take a number of abandoned but important projects. I can fully appreciate both sides.
I am wondering if there is something like a snippet database plugin for any text editor that would allow you to easily look things up without googling into Stack Overflow. Or maybe it would literally do that behind the scenes.
Because there are so many times where you just need a short example of how to use something so you get the syntax and core parameters or whatever right. Even for basic things like making a table in markdown. Which I think uses the pipe bar and hyphens but not sure.
I second .md support.
Can you please give a page-wide dark-mode option, and even each section?
- It should also be able to generate a pdf on demand
- It should have support for asciidoc (generate output in it)
- You should realize that requesting random features to a 1-person FOSS project in a derogatory way is not cool - You should offer to pay or help out if you want features - You should consider working on communicating more nicely is an important skill
How would you phrase a feature request?
So it's not the easiest way to create a readme.
Maybe flip your phone horizontal and request desktop site?
The reason it's not done yet is because I have a job and this is a side project :)
https://public-001.gitsense.com/insights/github/repos?q=wind...
And look at the impact chart at the bottom, it has all the signs of a healthy/popular project. A high number of contributors in Zone 3 indicates strong interest. A decent number of contributors in Zone 2, indicates high individual contributions to the project. And having no contributors in Zone 1 is the most important, as it means the work is being fairly distributed among Zone 2 contributors.
Normally for a project to be this fresh (23 days), you would expect somebody in Zone 1, but there isn't any, which is a very strong indicator of popularity and an even distribution of work that should make it more viable in the long run.
Note: Don't install my tool as the license in the docker image is out of date and needs to be updated.
Edit: Any reason for the downvoting? I know it is my tool but it does show insights that is relevant to the repository.
Secondly, I suspect some people may not like the idea of these kind of metrics.
I didn't downvote, but you could do this kind of analysis on any link to a github repo and I don't think people want it to become a habit.
It's still very unclear that the left quadrant is a mini-map of the other three quadrants. I recommend just graying out the top left and writing "Zone 1 - High Impact" somewhere inside the quadrant it describes.