[DOCUMENTATION] Does the documentation need improvement?

[JaffaKetchup]

Hi all,
One common issue I've noticed with this repo is documentation. For a large repo, the README is tiny and contains all the out-of-code documentation available.

These are just some of the issues I could find:

• Some documentation is missing
  • This StackOverflow question
  • Add Polygons drawing #77
  • Fill closed Polyline with different color than border #972 (comment)
  • Please add screenshots to readme.md #971
  • What's the recommended way to make plugins? #895 (comment)
  • https://github.com/fleaflet/flutter_map/projects/1#card-24327391: none of these seem to still exist
  • There is not a single point in the README that mentions the MapController()
  • There is no mention on how to build good plugins and use the plugin API
  • and many more closed issues that could've been fixed much quicker by better API documentation
• Some documentation is old/could be improved
  • According to this page, the README has only been changed around 65 times compared to the 612 commits in total
  • Some of those were just adding plugins, or fixing minor mistakes
• The API documentation is lacking
  • On pub.dev, 10 points have been lost due to lack of 'dartdoc' compatible documentation: only 18.3% of public API elements have documentation
  • The auto generated docs look relatively empty compared to a package (that I understand is much bigger) that has 16 of the 22 public API elements documented; so where do people go to find out what something does?

Fixing the documentation will cause a massive reduction in issues both here on GitHub and on StackOverflow.

It will also give plugin owners a bit more space to describe what they're plugin does and what problems it can help solve, rather than being shoved down to the bottom of the README.

So what do you think? Please see #927 (reply in thread) for options.
Thanks :)

[ibrierley]

I think firstly what you've done is good, and definitely the docs need a revisit. I think the docs are sometimes one of those things where people don't necessarily feel confident or have enough authority to write them, and full praise goes out to those who do :).

Only thing I'm bit wary of is splitting documentation into different sources that different people feel responsible for, then maybe they go inactive, or people don't know what to update etc. So I like what you've done, but with a certain wariness :). Could it not be done in the flutter_map git repo at all ? I'd rather have what you've done than not at all though :).

[JaffaKetchup]

I was thinking about doing it through GitHub's wiki system, which would be a lot better, but the way the wiki works is really annoying.
The wiki is a separate repo (flutter_map.wiki.git) so you can't open pull requests and you can't transfer ownership (as far as I know).
I agree, a wiki would be better because then supposedly it's easier to edit and it means everything is in the same place, but getting that wiki started on here without write permissions is a pain.
But yeah I can see your issues with if I go inactive.

Maybe a solution for that is I write it all to start with. Then I disconnect my Google and GitHub from it (I think I can do that, or I just export it), and change the owners email to one of the maintainers who's willing to do it? They could then change the password, icon and name and as long as they keep the username as fluttermap (used in URL), then that might work?

[kengu]

What about using the toolchain for documentation bult into github called GitHub Pages? (not wiki)? This will allow us to collaborate to maintain the docs, and it is all checked into code in a special branch.

[JaffaKetchup]

Actually that's quite a good idea! You can choose templates etc. can't you?
Great thinking! And that way PRs can be submitted for it.
Edit: looking at jeykll (I forgot how to speel), it looks great for this, and should be really easy to use considering its based of markdown. Maybe at some point in the near future I'll make a draft pull request for it. Thanks!

[TheLastGimbus]

Maybe some readthedocs? I didn't ever make them myself, but they are pretty convinent to use and search through 👍

[JaffaKetchup]

I've seen that used commonly in Python packages, and it looked decent, so maybe I'll have a look at that as well.

[JaffaKetchup]

I've submitted a draft PR! #975

[ibrierley]

Well, in the absence of any other suggestions for a while, I'm happy to go with any :D.

[JaffaKetchup]

Also, @kengu you know you asked how easy to work with locally, I just got it running in about 5 mins on localhost. Just follow the guide on the site https://docusaurus.io/docs/installation. But for me, I just closed @themisir's repo and npm installed docusaurus, then npm run start inside docs dir.

[themisir]

Superficially speaking, Docusarus looks the best. But the question remains which is easiest to work with locally.

You'll just need to install nodejs (and yarn if you want, which is a bit faster than node's default package manager - npm). And you can start local development server by just running the following commands.

yarn
yarn start
# or
npm install
npm run start

The dev server automatically hot refreshes page when you change files.

I see, @themisir, are you comfortable with deploying to GitHub Pages like the link says instead of Vercel?

Yep we can use whatever works for everyone.

it looks like deployment can be automated with GitHub actions, #927 (reply in thread), which we could include in the docs PR.

The only issue with this is, as far as I know, github only provides 1 public pages deployment meanwhile alternatives like vercel generates url's for each commit.

But I think it's not that important feature for now. So github pages will be enough for now.

[JaffaKetchup]

Cool, looks like we've reached an agreement? Shame we can't get that early commit version thing, but I agree it's a sacrifice worth making. Btw, I've locally cloned your project and got started editing on the first page with the local environment. I've also made sense of the config and read some of the Docosaurus docs.
Whichever way works best for you, I can either PR every update I make to your fork, or you can give me write access to your fork so I can commit instantly?
I'm quite excited about this, flutter_map will finally get the documentation it deserves!

[themisir]

I've modified the file structure a bit (separated docs and website related stuff to different folders), would suggest pulling last version.

[JaffaKetchup]

Ok, I will pull. Shall I do PRs for the updates I've made, or will you give write aceess?

[themisir]

I've recently come across docusaurus (built by facebook) which has a nice UI and somewhat widely used by react community. I can setup a github actions pipeline or we can use netlify or vercel to automatically generate documentation for each commit.

PS: I'll probably going to widely use this package in my apps, so I would like to contribute to its development & community, so I would be happy to collaborate in documentation.

[JaffaKetchup]

Understandable, and fantastic.
Overall, I think this is probably the best option, because it solves the most trade-offs:

• + Remains in repo
• + Reasonably good styling (two themes)
• + Good navigation
• + Supports markdown pages
• - A little complicated to deploy perhaps?

This is now my favourite choice, but still need a maintainer to confirm this is ok to start re-documenting with this platform. @kengu @johnpryan

[JaffaKetchup]

I've closed my Documentation Improvements PR in favour of Docusaurus. But if maintainers still decide GitHub Pages, then it can be reopened.

[themisir]

• A little complicated to deploy perhaps?

Actually, it's not that complicated. Could be deployed without any configuration. Perhaps I did a bit of configuration to configure header links, index page, footer, etc...

But unlike its alternatives like github pages (jekyll) and gitbook, it requires a bit of configuration.

And lastly, it does supports content search using Algolia (https://docusaurus.io/docs/search).

[JaffaKetchup]

Nice. I think @kengu supports, #927 (reply in thread)

#927 (reply in thread)

[JaffaKetchup]

@themisir #927 (reply in thread)

[ibrierley]

I'm fine with any as long as there's flexibility to edit from others (or at least easy approvals, or linked to a git profile or something) and won't go astray if someone goes awol :D. Things like Syntax highlighting for Dart is a bonus as well, not sure if they all do that. Would be preferable not to have yet another login, but ultimately, there's likely to be some tradeoffs.

[JaffaKetchup]

Yeah, the issue with going for external providers is it is more security to consider, but the advantage is it looks better and is easier to use and navigate.

[JaffaKetchup]

New visitors to this discussion who missed it, see this comment for options: #927 (reply in thread)