You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@baremaps.apache.org by Andrea Borghi <an...@gmail.com> on 2022/10/26 08:49:00 UTC
rethink of the Readme.md at the root of the project
Hi guys,
I was thinking: in my personal experience I generally like when I land on a project, and at a first glance of the readme I get the necessary infos to build and start "playing" with the project.
I think that the current readme does not allow for this "copy/paste and let's go" feeling.
The structure that I would suggest (and most probably do a PR if you agree) would have a few sections more for both "let's compile and run" in the readme and also a couple of TLDR sections based on the examples, and then links to more "in depth" and detailed examples etc.
What do you think?
Cheers
Andrea
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Josh Fischer <jo...@joshfischer.io>.
Sorry, I misspoke on your (1.) point. I haven't followed the legal
side much as of yet. I'll check into this and see what I can find
about if this is the logo submitted, etc.
On Wed, Oct 26, 2022 at 6:41 AM Josh Fischer <jo...@joshfischer.io> wrote:
>
> 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
> <an...@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.borghi@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-unsubscribe@baremaps.apache.org
> > > For additional commands, e-mail: dev-help@baremaps.apache.org
> > >
> > >
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Josh Fischer <jo...@joshfischer.io>.
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
<an...@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.borghi@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-unsubscribe@baremaps.apache.org
> > For additional commands, e-mail: dev-help@baremaps.apache.org
> >
> >
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Calvin Kirs <ki...@apache.org>.
+1 to keeping baremaps as the name,
btw, as I mentioned before, If the final discussion is unanimous, then
it's best to submit a ticket to the brand team to approve the name as
soon as possible.
On Thu, Oct 27, 2022 at 11:43 PM Josh Fischer <jo...@joshfischer.io> wrote:
>
> +1 to keeping baremaps as the name.
>
> On Thu, Oct 27, 2022 at 10:04 AM Bertil Chapuis <bc...@gmail.com> wrote:
>
> >
> >
> > > On 27 Oct 2022, at 15:32, Josh Fischer <jo...@joshfischer.io> wrote:
> > >
> > > 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?
> >
> > Originally, I thought that we would have to release the domain names (
> > baremaps.com, baremaps.org, baremaps.net) while entering the incubator
> > and I was worried that someone else may register them. Therefore, we
> > initiated a discussion about the name. Eventually, as there is no trademark
> > on baremaps, we submitted the proposal with this name without finishing the
> > discussion.
> >
> > If there is no other reaction to this thread I suggest that we simply keep
> > the baremaps name.
> >
> >
> > --
> Sent from A Mobile Device
--
Best wishes！
CalvinKirs
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Josh Fischer <jo...@joshfischer.io>.
+1 to keeping baremaps as the name.
On Thu, Oct 27, 2022 at 10:04 AM Bertil Chapuis <bc...@gmail.com> wrote:
>
>
> > On 27 Oct 2022, at 15:32, Josh Fischer <jo...@joshfischer.io> wrote:
> >
> > 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?
>
> Originally, I thought that we would have to release the domain names (
> baremaps.com, baremaps.org, baremaps.net) while entering the incubator
> and I was worried that someone else may register them. Therefore, we
> initiated a discussion about the name. Eventually, as there is no trademark
> on baremaps, we submitted the proposal with this name without finishing the
> discussion.
>
> If there is no other reaction to this thread I suggest that we simply keep
> the baremaps name.
>
>
> --
Sent from A Mobile Device
Re: rethink of the Readme.md at the root of the project
Posted by Bertil Chapuis <bc...@gmail.com>.
> On 27 Oct 2022, at 15:32, Josh Fischer <jo...@joshfischer.io> wrote:
>
> 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?
Originally, I thought that we would have to release the domain names (baremaps.com, baremaps.org, baremaps.net) while entering the incubator and I was worried that someone else may register them. Therefore, we initiated a discussion about the name. Eventually, as there is no trademark on baremaps, we submitted the proposal with this name without finishing the discussion.
If there is no other reaction to this thread I suggest that we simply keep the baremaps name.
Re: rethink of the Readme.md at the root of the project
Posted by Julian Hyde <jh...@apache.org>.
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 <ki...@apache.org> wrote:
>
> On Thu, Oct 27, 2022 at 9:32 PM Josh Fischer <jo...@joshfischer.io> wrote:
> >
> > On Wed, Oct 26, 2022 at 8:00 AM Bertil Chapuis <bc...@gmail.com> wrote:
> > >
> > >
> > >
> > > > On 26 Oct 2022, at 13:22, Antoine Drabble <an...@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.borghi@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-unsubscribe@baremaps.apache.org
> > > >> For additional commands, e-mail: dev-help@baremaps.apache.org
> > > >>
> > > >>
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
> > For additional commands, e-mail: dev-help@baremaps.apache.org
> >
>
>
> --
> Best wishes！
> CalvinKirs
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
> For additional commands, e-mail: dev-help@baremaps.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Calvin Kirs <ki...@apache.org>.
On Thu, Oct 27, 2022 at 9:32 PM Josh Fischer <jo...@joshfischer.io> wrote:
>
> On Wed, Oct 26, 2022 at 8:00 AM Bertil Chapuis <bc...@gmail.com> wrote:
> >
> >
> >
> > > On 26 Oct 2022, at 13:22, Antoine Drabble <an...@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.borghi@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-unsubscribe@baremaps.apache.org
> > >> For additional commands, e-mail: dev-help@baremaps.apache.org
> > >>
> > >>
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
> For additional commands, e-mail: dev-help@baremaps.apache.org
>
--
Best wishes！
CalvinKirs
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Josh Fischer <jo...@joshfischer.io>.
On Wed, Oct 26, 2022 at 8:00 AM Bertil Chapuis <bc...@gmail.com> wrote:
>
>
>
> > On 26 Oct 2022, at 13:22, Antoine Drabble <an...@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.
>
>
> [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.borghi@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-unsubscribe@baremaps.apache.org
> >> For additional commands, e-mail: dev-help@baremaps.apache.org
> >>
> >>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Bertil Chapuis <bc...@gmail.com>.
> On 26 Oct 2022, at 13:22, Antoine Drabble <an...@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.
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?
> 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.
> 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].
> 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?
[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.borghi@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-unsubscribe@baremaps.apache.org
>> For additional commands, e-mail: dev-help@baremaps.apache.org
>>
>>
Re: rethink of the Readme.md at the root of the project
Posted by Antoine Drabble <an...@gmail.com>.
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.borghi@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-unsubscribe@baremaps.apache.org
> For additional commands, e-mail: dev-help@baremaps.apache.org
>
>
Re: rethink of the Readme.md at the root of the project
Posted by Bertil Chapuis <bc...@gmail.com>.
> On 26 Oct 2022, at 13:17, Josh Fischer <jo...@joshfischer.io> wrote:
>
> I ran `mvn clean install` and that worked fine, but I'm thinking "what
> do I do next”?
From the terminal:
unzip baremaps-cli/target/baremaps.zip
export PATH=$PATH:`pwd`/baremaps/bin
From IntelliJ:
https://github.com/baremaps/baremaps/tree/main/.run
We should indeed have this in the documentation ;)
Re: rethink of the Readme.md at the root of the project
Posted by Josh Fischer <jo...@joshfischer.io>.
From what I can see the README and documentation shows how to download
already created executables. but doesn't show how to package a release
of baremaps or run it locally.
I ran `mvn clean install` and that worked fine, but I'm thinking "what
do I do next"?
On Wed, Oct 26, 2022 at 4:43 AM Andrea Borghi
<an...@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-unsubscribe@baremaps.apache.org
> For additional commands, e-mail: dev-help@baremaps.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Andrea Borghi <an...@gmail.com>.
- 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-unsubscribe@baremaps.apache.org
For additional commands, e-mail: dev-help@baremaps.apache.org
Re: rethink of the Readme.md at the root of the project
Posted by Léonard Besseau <l....@gmail.com>.
>
> > - The live reloading feature (dev mode) is quite unique but often goes
> under the radar. Should we make a gif or a video?
>
I agree. The hot-reload is a feature that you often see advertised and is
one that is really appreciated in projects that offer it. A gif seems like
a good way to demonstrate the ability.
> > - Cartographer wants to create maps and developers want to code. Should
> we make have two different quick start guides?
>
I think two guides is a good idea. For the cartographer, we could use one
of the examples like the openstreetmap or the extrusion to allow them to
get a feel of the project.
Re: rethink of the Readme.md at the root of the project
Posted by Bertil Chapuis <bc...@gmail.com>.
> 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