Prepare For New Documentation

[JaffaKetchup]

• Replaces majority of README contents with link to new documentation website, available at https://docs.fleaflet.dev
• Changes issue template selector to reflect this change
• Added Code Of Conduct and Contributing information to conform with GitBook's Open Source Plan requirements

Replaces #992.

[ibrierley]

Hmm I'm a bit uncertain on this one as it is, I didn't realise the intention was to remove the current readme info....

I think the detail is good, however, I feel like what's missing that was actually useful from the Readme is the quickness of being able to instantly see widget examples in use and plugins.

Maybe it's the front page (of https://docs.fleaflet.dev/ ), it leaves me scratching my head a bit if there is no readme as well ? How do I quickly get to see a typical flutter_map set of code ?

[JaffaKetchup]

Good point that I missed.

I'll add a quick example to the front page of the documentation, if you think that would be suitable. Something like what was already on the README.

I'd like to keep the README simple, so it doesn't need changing very often from now on.

[ibrierley]

I think there's typically a couple of different ways people use docs. One is more of a quick scan "just show me the examples, can I get my head around it, and I don't want to have to search", and the other more of a "I've used this a bit, but now I need to dig into more detail on a certain aspect and don't mind searching a little to get there". Often fiddly getting the balance.

There's probably some key aspects more important than others, eg mapController, widget layers, plugins etc, and then others less so, boundaries, TileMill that can be dug out if needed etc.

[JaffaKetchup]

I've made some changes, see what you think now. Happy to change it more!

[ibrierley]

Not sure I know what's changed (what has changed?)...I'm also not sure if I'm missing something. Anyway, looking at https://docs.fleaflet.dev/ for example (I'm kinda including that as part of the comments on this PR if the readme goes minimal..).... I don't think the feature highlights are useful here for most people that will hit the site.

Maybe in my mind it would better just linking to https://docs.fleaflet.dev/usage/basics (or having that as the front page iyswim ? I think maybe it's important to have the left hand menu visible on first entry to the docs site.

Also maybe the Example page could link direct into the examples folder on Git.

As an aside (so for another day), it could be interesting to have a live example running (eg https://fluttermap.dabbles.info/v0.15/#/ but on a proper domain, not sure if that could be done in git easily and then a link to the github examples folder so people could look at the code and test the example if that makes sense)

[JaffaKetchup]

Hi,

I added a code snippet to the front page and also made the menu visible on that front page. I would prefer to keep the highlights, as a filler but also a quick reference people can use if stuck between which library to choose for their app.

I removed the documentation page and just changed it to an external link straight to the GitHub folder.

I like the interactive demo idea. Maybe this needs to be hosted somewhere and redirected to from 'demo.fleaflet.dev' or something like that.
I have experience with setting up automatic build and hosting of a Flutter project on Firebase Hosting (free for our use) via GitHub Actions, and connecting to a custom domain: my 'jaffeketchup.dev' uses this strategy. I'm happy to set this up, it shouldn't be too difficult.

[ibrierley]

Ok, I was about to say I couldn't see the code snippet and getting confuddled, however I think what's happening sometimes is Chrome (or other) is showing me an old cached version of the page, and why sometimes I may have been a bit confused! Now I know to force a cache update everytime I look :).

Looks a lot better now I'm looking at the correct updated page! Apologies for any previous confusion. Nav etc on the LHS all looks good now to me.

Very Minor tweaks:
In the Wide Ecosystem of Plugins. Could add an "Click here to look at the plugins" or something.
On the Controller page, just swap see the Common Errors page, to Common Issues page (or swap the link name)

May be handy at some point to have a link on caching and crs, then I think the original readme is pretty much covered as well.

[JaffaKetchup]

Yeah that does happen :D

I've added a plugins link, and fixed the common issues link, but I'm leaving the CRS out for now, as that is only useful in the WMS section which hasn't been written yet (I need some help with that, not sure what I'm doing). Caching is done already, but I couldn't find an appropriate place to put a link for it.

What do you think about the demo thing?

[ibrierley]

I think my only chin scratcher still, is I'm just thinking that maybe the example link should go to https://github.com/fleaflet/flutter_map/tree/master/example/lib/pages (and "online documentation" link on https://github.com/fleaflet/flutter_map/tree/master/example go to the new docs?).

As we're now an extra step away from the code, maybe it just feels a bit more important to make all the examples a bit easier to find, as they're very useful (and the current main example page "feels" like either it needs redoing, or just link past it to the actual code examples) ?

[JaffaKetchup]

I've added a link from the example directory README to the online docs now. I'd prefer to keep the link from the documentation site how it is, as I've added a bit more text to that README as well on usage etc.

Not sure what you mean by 'current main example page'? The README (if so, is what I've done good for you?) or the app's home page?

[ibrierley]

Yes, sorry, I meant the readme in the examples folder.

I still think its too hard to get to find all the separate examples though which is the most useful part (and then we just get asked a question "how do you do X" and we point them to the example, would be nice to cut out the middle man there.

If @johnpryan or @kengu or anyone else are fine with it, I'm happy though!

[JaffaKetchup]

So, something like a list of features and the corresponding example page?

[ibrierley]

I'm not sure it even needs a list of features...i.e would a link to https://github.com/fleaflet/flutter_map/tree/master/example/lib/pages just be enough (it would be better to have a list of examples in the example/readme, but I was trying to avoid having to have anything that needs updating in the future iyswim).

[JaffaKetchup]

Sure, I see now. I'll update the website link in that case.

[JaffaKetchup]

All done (website example link updated).

[ibrierley]

Super, thanks (sorry for any confusion, and chrome cache got me again!). I think that's good now, and happy to be merged. Can always revisit later if anyone has any thoughts.

[JaffaKetchup]

Ok, don't merge just yet. Going to do one last update of the CHANGELOG.