| Some questions I have are - what is this - how do I pronounce the name (note there's a popular crypto tool called "age", which is "pronounced like the Japanese 上げ (with a hard g)") - what are the alternatives (regular postgres, dgraph, neo4j, ...), and how do they compare, along whatever dimensions you like (performance, guarantees, scale, ease of use, license, ...) - what are some use cases that are good for AGE vs the alternatives - when do I not want to use this - what does simple example usage look like - what is the maintenance status, what does "(incubating)" mean, etc But the github readme is a first-glance place, and once I've made it to the docs I might not go back to the readme. So the docs need to contain all that information. |
When mentioning pronouncing in Japanese, I would think that it would be better to use entirely kana, rather than kanji or mixed kanji/kana. (When writing actual words/sentences, I think mixed kanji/kana is better, but for writing pronounciation, I think kana alone is better.) (Note: I don't know so well understanding Japanese, but I can pronounce words written with kana, at least.)
> But the github readme is a first-glance place, and once I've made it to the docs I might not go back to the readme. So the docs need to contain all that information.
At least some of the information, yes. Any information which is relevant to the use of the project should be mentioned in the documentation, including the license, although the documentation might not need to contain screenshots, a list of alternatives, etc.