[GIP] write user-level mapstore documentation / overhaul georchestra documentation

[landryb]

Who ?

CRAIG / @landryb / @MarieSuet

Target Module

Mapstore first, & other georchestra modules second.

What ?

The community resorts to:

• mailing lists
• upstream projects documentation, which might not 100% match with the integration of the project within georchestra (a good example is the user guide for mapstore which talks about a homepage we dont have: https://mapstore2.readthedocs.io/en/latest/user-guide/home-page/)
• lacks a central place to find them all

we need to improve that.

Why ?

We need to overhaul our documentation, as already noted/discussed in georchestra/georchestra#3791

our users dont have a proper french documentation for mapstore2, and some initiatives already started some instance-tailored word/pdf documentation (rennes, le puy en velay cf https://geoportail.lepuyenvelay.fr/prise-en-main-de-mapstore2/) but it would be better to have:

• something online, browsable like on RTD
• generic
• easily findable by georchestra users

How ?

• right now there's a repo at https://github.com/georchestra/georchestra_documentation but it's only/mostly sphinx configuration. it doesnt hold actual documentation
• the proposal is to have versioned docs for georchestra versions by branches, maybe in this repo, or in https://github.com/georchestra/mapstore2-georchestra/ which has some ReST doc.
• using mkdocs or sphinx, whatever, but as long as documentation is preferably written in markdown and not ReST.
• we've already gathered some experience with mkdocs/markdown for some teaching documentation at CRAIG by @MarieSuet and we'd like to reuse that for georchestra.
• Upstream mapstore uses mkdocs/markdown for their documentation, as https://georchestra-user-guide.readthedocs.io/en/latest/

Any potential pitfalls and ways to circumvent them ?

as every documentation, it tends to get outdated/not in sync when the subcomponents are updated..but at least having something would be better than nothing.

having versioned docs would allow to clearly state against which version a documentation was written.

the proposal is to start by mapstore user doc in french (yeah i know..), then other components (console...)

When ?

work might start before the end of the year. No specific release is targeted, but at least documenting the current mapstore releases (2022.01, etc..)

Votes

Project Steering Committee

• @fvanderbiest : +1
• @pierrejego : +1
• @jeanpommier : +1
• @landryb : +1
• @smevel : +1
• @catmorales : +1
• @MaelREBOUX : +1
• @pmauduit : +1
• @fphg : +1

Community support

• @vfabry : +1

[fphg]

thanks @landryb this proposal seems relevant to me
i'd add a matching version number in any doc, assuming some users may print it

[geo-grandest]

Documentation is an important point for us too in DataGrandEst and a limit for developpement of using applications like MapStore.
Markdown is better than ReSt for me.
I already test mkdocs (with mkdocs-material plugin) for a project (cf. https://www.datagrandest.fr/tools/dge-dataviz-components/documentation/index.html - not yet linked to a GitHub repository) and it's a good choice according to me.

[fvanderbiest]

+1

If the documentation is mapstore-specific, it is best located in https://github.com/georchestra/mapstore2-georchestra/

If the goal is to write a documentation for geOrchestra, then another repository should be used. BTW, there's already plenty of content in https://github.com/georchestra/data-admin-book/tree/master/fr

[catmorales]

What about the documentation made by geosolutions : https://docs.georchestra.geo-solutions.it/en/latest/ ?
It should be an entry point to the documentation no ?
Source is in https://github.com/georchestra/mapstore2-georchestra/tree/master/docs/source , I think.
If we want to change the format, it will be necessary to modify this one too.

[catmorales]

The PSC is opening the review of this proposal.
Will be close on the 15/12/2022.

[pierrejego]

+1

[jeanpommier]

+1

[landryb]

obviously voting 👍

[MaelREBOUX]

+1 for this proposal.
We really need that.
Then we should discuss on the how. See this on january 2022.

[smevel]

+1

[catmorales]

+1

[vfabry]

+1

[pmauduit]

👍

[fphg]

+1

[landryb]

Everyone in the PSC voted, the GIP is now Adopted, this issue will be linked at by future work implementing it.

[MaelREBOUX]

I reopen and add the "work in progress" label ;)

[MaelREBOUX]

To follow since the hackaton ended yesterday in Rennes :

• big improvement on https://github.com/georchestra/georchestra_documentation/ we now have :
  • a documentation template
  • in mardown
  • make with MkDocs
  • and a documentation four using / contributing (work in progress)
• https://docs.georchestra.org/ is now a beautiful HTML page

I let this issue open until we got finished some points :

• cadastrapp documentation switch
• mapstore2 documentation switch
• documentation template

[MaelREBOUX]

The new cadastrapp documentation is avalaible since june 2023.

https://docs.georchestra.org/cadastrapp/