Sure, I"d be happy to. Overall I agree with the points you made. Let me do a little thinking/digging through the code and see what I come up with.
On Wed, Oct 26, 2022 at 6:22 AM Antoine Drabble <antoine.drab...@gmail.com> wrote: > > 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 > > > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@baremaps.apache.org For additional commands, e-mail: dev-h...@baremaps.apache.org
