🖥Smart Maps Documentation Sub-working group

[albertkun]

Please comment in this thread or add your self to volunteers if you are interested in working with Smart Maps sub-working group by 4/21 (4/20 PST)!!

Purpose

• Who is the documentation for?
  • Recommended languages:
    • English
    • Japanese

Implementation

• What tool would we like to use?
  • Recommendation
    • Material Mkdocs](https://squidfunk.github.io/mkdocs-material/)
    • Docusaurus

Existing Resources

• Objective-7 have tried to write documents in Markdown and convert it into Web site on GitHub Pages
• UNVT Training list

Volunteers

• @albertkun
• @hfu
• @ubukawa

Next steps

• Have a list of volunteers above and schedule a meeting to decide on:
  • Target audience - who is this for?
  • Documentation authoring tool - how will we be building/maintaining this tool?
  • Smart Maps Content - what content should be included
    • Create a Use Case Catalog

[hfu]

@albertkun Thanks your your contribution!

Do you think it is a good idea to include other outreach items such as #88 and #115 to "Documentation Sub-working group", or shoud we think about them separately?

[albertkun]

@hfu You are welcome! Thank you for providing a positive and welcoming space!

Personally, I think it depends if we want to use the Documentation as either:
a) Smart Maps Volunteer Hub that "documents the working group"
or
b) Smart Maps technical documentation that "documents technical aspects of the working group".

Under a) yes! It would make sense to pull together all outreach material, like #88 and #115, and share the process of how Smart Map does stickers and community cards.

With b) the documentation would be more limited to explaining and training on how anyone can use the deliverables that the DWG7 is working on, like UNVT or the Smart Map Bazaar.

We can also combine the two a) + b) but, I think a key for successful documentation is knowing who it is for, so we can target those people first.

Your input as the lead on DWG7 would be extremely valuable on how you think we should proceed!

[hfu]

Thank you, @albertkun. I tend to like to write documentation which only we can write like a project document. In addition, I tend to focus on developer happiness rather than capacity building. So my initial idea is a) above.

On the other hand, I suppose @ubukawa is a good document writer for capacity building as in b). I see he is also a motivated writer to help and train others.

Another suggestion is that we can more casually document by sharing idea sketches and work logs so that we developers can motivate each other. I named this concept 伝習 (Denshu) but I would say that this approach was not a big success.

I personally like to follow a) where we write the document for existing and future DWG 7 participants.

[albertkun]

@hfu Thank you for your thoughtful reply!

I like the idea of a) as above and would love to also include 伝習 as well for existing and future DWG 7 participants.

Even by going with a) we can still make b) a sub-section of the documentation.

Overall, this is a good start to focusing in on the content!

[albertkun]

@hfu @yuiseki For the time being, as a proof of concept, can I copy some of the content over from the Wiki and Objective 7 repository?

[yuiseki]

@albertkun Of course, you are most welcome! Objective 7 repository is MIT License, so you can redistribute it freely!

[hfu]

@albertkun Of course there is no problem to make a copy and improve the Project document. I really appreciate your effort.

Meanwhile, I was thinking about using ChatGPT to summarize the Project document ;-)

[albertkun]

@hfu @yuiseki Thank you for both your support! Should we create a new repository?

If so, may I suggest: https://github.com/UNopenGIS/7-docs?

I think we should definitely use ChatGPT where we can to streamline! 😄🤖

[hfu]

Yes, '7-docs' would be a good name.

I invited @albertkun to the 'unopengis' organization with an owner role.

[albertkun]

@hfu Thank you very much! I'll get started just putting together existing resources so that when the Documentation sub group meets we can discuss how to improve it! 🙂

[ubukawa]

Dear @albertkun
Thank you for your effort!
I am interested in working with you.
(But, I am still at my transition period, and I am not sure about my next responsibility allows me to spare some time for it. Please register me as a volunteer with such consideration;D)

For your informaiton, I wrote my Qiita articles for the following audiences:

• My UN colleagues (to explain the background of our vector tile tools)
• My UN colleague who will take my job responsibility of taking care of vector tile]
• Myself (I often forget some command, so it is a kind of my technical note)

I think that the term "Smart Maps" can cover various things, and it is not practical to develop all documents for all the topics. As you already discussed, I think starting from the possible audiences and training would be a good idea.

I look forward to working with you!!

[albertkun]

Thank you for your support and feedback @ubukawa !

No problem about your transition period! I agree that "smart maps" can mean various things, including the UN Vector Tile initiative! We should make sure to have a place to put your helpful training, so it is great that you will be helping us to work on the Documentation!

Excited to be working with you!!

[albertkun]

For those interested, the documentation repository is:

• https://github.com/UNopenGIS/7-docs

The current documentation (beta) is here:

• https://unopengis.github.io/7-docs/ (English)
• https://unopengis.github.io/7-docs/ja (Japanese / 日本語)

[albertkun]

@hfu @ubukawa (@yuiseki?) could we schedule a working meeting next week for Documentation and explaining how to add content! I'm pretty flexible but would like to suggest Friday 4/28 at 1pm JST (4/27 at 9pm PST) time! Please give a thumbs up or comment with an alternate time/day!

[hfu]

I created a separate issue on the working meeting at #137.

[albertkun]

Thank you for creating the separate issue @hfu! Will follow-up on it!

[yuiseki]

Forgive me for writing one-sidedly about my thoughts.
If you like, please use it as a reference.

What we are doing in this working group is in fact very diverse and complex, but it may be easier to understand if we divide it into the following layers, as in the OSI model, for example

---

Layer 1: GIS data format layer

• Understand industry standards for what data formats geospatial information should be handled in computing
• Also, an understanding of projection, coordinate systems, and geodesy is included here
• This layer is the most important because it is the foundation for all upper layers
• (personal opinion)
  • The difficulty with GIS is that historically, the data format and the distribution and presentation are closely linked and progressing every day
  • I personally feel that this makes GIS difficult to understand for many beginners

Layer 2: GIS data construction, persistence, and retrieval layer

• Understand GIS databases like PostGIS
• Also, understanding and contribution to open data such as OpenStreetMap should be included here

Layer3: GIS data conversion and processing layer

• Understand how to convert and process GIS data as needed
• Certain GIS data formats may not be suitable for distribution or presentation
• In that case, the GIS data format must be converted or processed into another GIS data format
• Understanding the process of extracting only the required data from GIS data is also included in this layer
• A vast array of Linux commands exist for this conversion and processing

Layer 4: GIS data distribution layer

• Understand how to distribute GIS data so that end users can receive it
• This layer requires an understanding of not only GIS, but also Internet communication protocols, various cloud infrastructures, and in some cases, server management and operations

Layer 5: GIS data presentation layer

• Understand how to display the GIS data being delivered in a way that is easy for the end user to view and handle
• This layer requires an understanding of HTML/CSS/Javascript for web applications

---

The official documentation and official wiki are the most organized and complete in terms of individual documentation for each layer.
And practical techniques are already available as technical articles on qiita and other web sites.

I think the point of writing our own documentation is to help the reader quickly understand each layer and the connections between these layers, to see the big picture of Smat Maps, and to be able to reach existing resources and explore them on their own.

In other words, a common map, a big picture map about Smat Maps are what we should be written.

[albertkun]

@yuiseki Thank you very much for sharing your thoughts and providing a very detailed approach! I appreciate the summary of the objectives in the big picture level and the OSI connection you showed!

I agree that we shouldn't replicate what's already on official documentation, but rather (like you said) focus on how the layers are connected. The initial proposal was to create a hub for smart map related projects and use cases to show the bigger "what is smart maps" picture! I think we are in agreement, but let me know if you have any other comments or questions!

I hope you can join us for our meeting on Friday #137!

[yuiseki]

I'm obsessed with making large-scale language models contribute to humanity, so I developed something like this!
I would be happy if you were aware that this kind of thing is possible...

Introducing TRIDENT, an UN dedicated interactive document exploration and humanity assistance system.

https://trident.yuiseki.net/

This system currently targets only 18 English-language documents written by @ubukawa san for exploration,
However, as an architecture, the target documents can be expanded as much as possible.
For example, it is also possible to input and explore all UN resolutions in this system.

EDIT(2023-04-28T10:42+0900):
TRIDENT now possible to explore more documents, listed below

• 18 qiita articles
  • https://github.com/yuiseki/TRIDENT/blob/main/public/qiita.com/urls.txt
• 90 README.md of the GitHub repositories
  • https://github.com/yuiseki/TRIDENT/blob/main/public/github.com/urls.txt
• 400+ resolutions of UN General Assembly
  • https://github.com/yuiseki/TRIDENT/blob/main/public/www.undocs.org/urls.txt

This system does not write texts like ChatGPT instead of having limited capacity, so the chances of lying are extremely low.
(However, this system can be wrong answer.)

I release this system as free and open source software:
https://github.com/yuiseki/TRIDENT

Although not related to GIS, apart from TRIDENT, I have developed and operate a system called OPTIMIZER, which explores and summarises the welfare programs of the Tokyo Metropolitan Government's municipalities.

https://optimizer.yuiseki.net/
https://github.com/yuiseki/OPTIMIZER

This means that it is technically possible to not only search existing documents, but also to have them concisely summarised, depending on the user's requirements.

Key points:

• The Markdown format is an excellent format in which present large-scale language models can be accurately understood
• By allowing Markdown files to be explored in a large-scale language model, learners can search for and learn even ambiguous terms

[hfu]

Looks like we can close this issue because we are in the next stage. First engine cut-off.