I think that it's a very good idea to update the readme! I have quickly looked at a few readme files on Github from different Apache projects. Some projects like Hadoop or Calcite just link to an external website. Each readme is quite different.
I really like this one [1], which is another project in incubation. I have a few inputs that may or may not be useful to you if you make a first draft of a new readme. 1. I like the logo at the start, it looks more welcoming. That is probably another topic, but should we try to find a good logo, or is the logo on the Baremaps website our official logo? I really liked the DALL-E warbler images, maybe we could make a bird logo out of this? 2. Starting with "What is Baremaps" or "What can be accomplished with Baremaps" is very important I think. I imagine that as a new project in incubation, many people will just come to see what Baremaps is and leave as soon as they know what it does. 3. Link to the live demo for people who quickly want to take a look. If we add too much information before this, we might lose the reader's attention. 4. "Getting Started" or "Quick Start". Here I think we should redirect to other pages. As Bertil pointed out, some people will just want to use the CLI from a release and use a Postgis database that runs on Docker or Kubernetes. In some use cases, you don't need a postgis database. There will be other people that want to compile the code in an IDE. 5. The other sections could be useful as well such as "How to contribute", "Roadmap", "Community" (link to the mailing list maybe), "License"... [1] https://github.com/apache/incubator-devlake On Wed, 26 Oct 2022 at 11:43, Andrea Borghi < andreafrancesco.bor...@gmail.com> wrote: > - Were there parts of the documentation/examples that you had difficulty > understanding? > > it's more a problem to find them easily then understanding IMHO. > > > - Cartographer wants to create maps and developers want to code. Should we > make have two different quick start guides? > > that's a good point! > > > On 10/26/22 11:40, Bertil Chapuis wrote: > >> What do you think? > > It's a good idea, the documentation should help people get started > quickly. The migration to Apache is also an opportunity to revise the web > site [1]. > > > > Some additional thoughts/questions: > > - The live reloading feature (dev mode) is quite unique but often goes > under the radar. Should we make a gif or a video? > > - Cartographer wants to create maps and developers want to code. Should > we make have two different quick start guides? > > - Were there parts of the documentation/examples that you had difficulty > understanding? > > > > [1] https://github.com/baremaps/baremaps/issues/491 > > > > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@baremaps.apache.org > For additional commands, e-mail: dev-h...@baremaps.apache.org > >
