Glad you're thinking about the design of README.md. It is an important entry point to the project for developers (and potential contributors).
But bear in mind a couple of other entry points: the project's home page, and the source tarball. The home page should be the default entry point for people more interested in the project and community than the code, and for people interested in using the product. So, give some thought about the relationship between the two. And lastly the source tarball, which is what Baremaps will release. People expect to find some instructions in the tarball, generally a README or README.txt file. This file has a similar name to README.md, but has a slightly different purpose. In Calcite we discussed for a long time whether both files would contain instructions to build the project, or whether they would point to a third location. The results are here [1] [2] but I'm still not sure that we got it right. Julian [1] https://github.com/apache/calcite/blob/main/README.md [2] https://github.com/apache/calcite/blob/main/README On Thu, Oct 27, 2022 at 8:59 AM Calvin Kirs <k...@apache.org> wrote: > > On Thu, Oct 27, 2022 at 9:32 PM Josh Fischer <j...@joshfischer.io> wrote: > > > > On Wed, Oct 26, 2022 at 8:00 AM Bertil Chapuis <bchap...@gmail.com> wrote: > > > > > > > > > > > > > On 26 Oct 2022, at 13:22, Antoine Drabble <antoine.drab...@gmail.com> > > > > wrote: > > > > > > > > 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? > > > > > > The name is probably something the community should discuss and vote for. > > > Once the final name is set we can launch a contest on 99designs or on > > > another platform to create a logo. > > I don't think this is necessary. Unless you feel strongly about it. > > > > > > Josh, one difficulty most of us have as non-native english speakers is to > > > know if a name sounds good. What do you think of Apache Baremaps or > > > Apache Warbler? > > > > Either is fine with me, Would you give context on why you chose > > Baremaps or why'd you like to change it to Warbler? What is the > > meaning behind them? > > > > > > > 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. > > > > > > Yes, but we don’t want them to leave without doing something. > > > > Being able to get people to engage in the project easily is important. > > > > > > > 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. > > > > > > Yes. > > > > > > > 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. > > > > > > It looks like many projects have a landing page and publish documentation > > > for releases. Another nice reference is Apache Ignite[1]. > > > > I like when projects have a "quickstart" section for users and > > "developer" section for people who want to go deeper. > > > > > > > 5. The other sections could be useful as well such as "How to > > > > contribute", > > > > "Roadmap", "Community" (link to the mailing list maybe), "License"... > > > > > > Yes. Also, Apache has some guidelines and a checklist for web sites [2] > > > > > > Josh, do you have experience with the infrastructure for web sites at > > > Apache? > > I do. There are some things that need to be done to the website for > > compliance Apache (for sure), it looks like [2] outlines most of it. > If you need any help, feel free to contact me. > > > > > > > > > [1] https://ignite.apache.org/ > > > [2] https://github.com/baremaps/baremaps/issues/489 > > > > > > > > > > > > > [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 > > > > > -- > Best wishes！ > CalvinKirs > > --------------------------------------------------------------------- > 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
