As the founder of a quite similarly named company, this looks great :) Not sure if you're looking for a job Katherine, but if you are my email is in my profile!
I love the concept of Readme.io but I chose Sphinx over Readme.io for my startup despite starting out with Readme and really wanting it to work. A few issues:
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 would never try to dampen someone's enthusiasm for launching a company!
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 :)
You're exactly right - if you're writing readme's all the time, you'd have templates ready to go.
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.
I wrote a README.md template because I started a bunch of projects of my own in the last month but I haven't used it so far and it is not more than a bunch of headers plus a license boilerplate.
I went ahead and created vscode-readme it takes the templates used on readme.so and creates a snippet per section and if you use the readme snippet it combines all the sections https://github.com/ThreeCommaIO/vscode-readme. I just published to the extensions marketplace too.
This would be useful as part of the new repo creation workflow on GitHub too. Instead of just getting an empty readme, pick the sections you want and start with one that just needs to be filled in. Could autopopulate some sections too (eg, license). I’d rather that so I can edit in my regular editor without having to use a separate site and web editor to get that initial template.
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.
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.
"Price hike", really? I would not exactly call 6.67 euros a month a rip-off. Given your reaction to it, it seems like a very reasonable policy to ensure that people claiming a URL really have plans with it, while keeping out foreigners parking on Somalian webpace for the lulz.
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:
I'm old enough to remember personal websites being a thing, before everyone and their company went over on that Face Site. I had a personal site back than which IIRC 2010 or 2011-ish I moved to the domain I mentioned, and, at the time, I kept updating the site somewhat regularly (before than I had a .de domain, which was really darn cheap and the site was in German only).
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.
There's nothing ad-hominem in my response, I just question your assessment that 80 euros a year is forcing you to "pay through the nose".
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.
> 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.
Governments aren't businesses. They don't, and really shouldn't think of making money first. Top priority should be the interest of their citizens. Besides funding public services and utilities through fees and taxes, governments can use those to incentivize certain behavior, either by making it cheaper than doing otherwise, or by making it more expensive, i.e. penalize it.
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.
Choosing any price or deciding to boot non-citizens is their perfect right. Heck, I would even be in favor of country code TLDs only being used for stuff somehow related to those countries. I never claimed anything else, I just tried to point this out, because someone asked (see several postings up).
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.
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?”
Knowledge management is often forgot. When starting a new project I like to put some effort on summary, (planned) features, (expected) usage/API and license before I begin coding.
To me the biggest thing is that I don't make a lot of tables in markdown so being able to drag and drop that would be easier than looking it up. Although having a list of potential sections is helpful too.
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.
- 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
I guess if you normally create your READMEs on the phone, then no. But then, how often do you create READMEs on a phone? I can count on no hands the amount of times I've done that in my life.
I'm also on mobile. No, I've probably never had a need to create a README from my phone, but it would be useful to be able to learn about this service. I wonder what they're doing that's so complicated it doesn't work on mobile...
The mobile version is in progress. The layout doesn't quite work on mobile, and the editor library I used doesn't work on mobile, so it requires some tweaks.
The reason it's not done yet is because I have a job and this is a side project :)
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.
Well firstly, it's common courtesy to state it upfront if you have a conflict of interest (E.g. you work for the company being discussed or you're linking something of your own).
Secondly, I suspect some people may not like the idea of these kind of metrics.
Hey thanks for the candid feedback! As for the metrics, I will need to write more about impact based metrics as they are suppose to help developers. For example, it is a fast way to determine potential domain experts for code reviews and other things.
Oh! Well, you need a way to link to the page with the impact tab open, since I never noticed there were tabs at all!
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.
