Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How do I improve boring README page?

news.ycombinator.com

Post reply on HN
Print view View original

11–20 of 77 posts

Re: Ask HN: How do I improve boring README page?

#11

Post by Isognoviastoma »

Telling what concrete problem you solve already place you ahead of many Apache projects. "single storage that can handle both relational and graph model data". Some short example of usage would be nice too.

To illustrate, let's look at summaries of top popular projects (by number of commits, because that's what Apache shows on stats page):

> Camel is an Open Source integration framework that empowers you to quickly and easily integrate various systems consuming or producing data.

> Apache Flink® — Stateful Computations over Data Streams [here image of taking events and DB as inputs of process]

> Airflow is a platform created by the community to programmatically author, schedule and monitor workflows.

??? Why would i need them?

> Apache Spark™ is a unified analytics engine for large-scale data processing. > spark.read.json("logs.json").where("age > 21").select("name.first").show()

> Lucene Core is a Java library providing powerful indexing and search features, as well as spellchecking, hit highlighting and advanced analysis/tokenization capabilities.

These tell or show what they do. Good.

Re: Ask HN: How do I improve boring README page?

#12

Post by jakub_g »

Not directly answering your question, but something I'd appreciate in every readme:

- What problem is this repo solving / why would I use it (ideally explained in a way that a person who uses completely different tech stack could understand; this is a tough requirement though)

- What problems this repo does not solve and when I should not use it

- What are the alternatives and trade-offs

Re: Ask HN: How do I improve boring README page?

#13

Post by neolog »

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.

Re: Ask HN: How do I improve boring README page?

#14

Post by compressedgas »

To me a good README needs to:

- tell what the software does

- list its requirements

- explain how to set it up

It must do this only relying on local files.

The README of AGE meets some of these. The description could better. I'd open with: Apache AGE is an PostgreSQL extension that implements the openCypher property graph query language.

I would remove the latest happenings from the README and keep them on the project home page which I would have a link to right after the description.

I would also I would include the source of Apache_AGE_Guide.pdf in the repository. It is fine to have a link to the already formatted PDF should some one be viewing the README on a device where building the software isn't possible. But I would not want a user to download a snapshot or the repository and then discover that they have to have further internet access to get the documentation.

Re: Ask HN: How do I improve boring README page?

#16

Post by TeMPOraL »

Put yourself in the shoes of your users. What does a random user visiting your repo want to know? In my case:

- What problem does the software solve, and - roughly - how?

- How does it look? If it has any visual component, even if it's a CLI interface that's meant for human consumption, screenshots are mandatory. Screenshots + videos/ASCIInemas preferable.

- If there are alternatives you know of, mention them - be honest about when an alternative is a better fit than your project.

- What platforms does it work on? What are the requirements?

- How do I install it? In exact steps, for most common workflows. If that gets too long, link to a separate page containing these detailed instructions.

- How do I run it? Examples of common use cases, with exact invocations/procedures to perform.

- Any relevant remarks that could prevent me from installing or using the software.

- Links to further docs, project webpage, communities, etc.

When I evaluate a project - even briefly, skimming the repo README - these are all the points I'm on the lookout for - they're all helpful for deciding whether to look closer at the project, and possibly install and use it.

Re: Ask HN: How do I improve boring README page?

#18

Post by sails »

jakub_g wrote: post #12

Not directly answering your question, but something I'd appreciate in every readme: - What problem is this repo solving / why would I use it (ideally explained in a way that a person who uses completely different tech stack could understand; this is a tough requirement though) - What problems this repo does not solve and when I should not use it - What are the alternatives and trade-offs

> What problems this repo does not solve and when I should not use it

Second this, really can help if you're navigating through a few possible alternatives

Post reply on HN