Future of the Wiki

[kiozen]

The Wiki has been a highly valuable source of information for years. There is a lot of work in it. Especially @wthaem spent countless hours on it. And many others, too. However the Wiki grew a bit outdated or partly stall over the years.

This is very unfortunate considering the time already spent on it. To update, it would require another batch of countless hours of manual labor. More than I ever would dare to ask from anyone.

So what is the future?

In the past month I used a lot of AI. At work and for this project. AI is a two sided sword. If you do not know what you want and have no instinct on how good code and documentation should look like, AI will lead you into a gopher hear and you will never get out of it again. However if you closely review each step and intervene on the first sight of unreadable, to complex results it is a real help. A good example is the icon and dark theme refactor of the 1.21.0 release. The topic nagged at me for years but I did not touch it because of the complexity. With AI it was possible in a reasonable time frame.

At my everyday work projects I already established a triad of workflows when solving a ticket. Fix the code, update the tests, update the docs. By that every PR has a up-to-date documentation. And AI can verify if a change needs an update of documentation. This works fairly well. Another benefit: I am no native speaker for English and I am not very good in writing documentation. AI is way better.

So I asked the AI if there is kind of hope for the Wiki. As usual take it with a grain of salt. This has not been refined and the AI got some details wrong. But the general outline is reasonable. That is the answer:

wiki-modernisation-plan.md

In short:

• There is quite some stuff that can be updated by AI reading the source code and refactoring the pages.
• Many content (Group 2) is hard to be written by the AI

The idea to move everything into the project's docs folder is inducted by me. This is how github would prefer it today. Makes sense if you want to update docs in PRs.

The (huge) caveat:

The obvious one: You need AI that can tinker with files on your hard disk. And this is nothing you get for free. You need a subscription and this will cost you at least ~20€ a month. Too much to ask anyone to pay just for updating the documentation. If you have a subscription anyway it would be ok.

The next problem: I need help on that. My time budget is always on the edge. I still work and have a company to run. Answering tickets, review of PRs and tackling tasks in the code, that I do not want to ask anyone else for, consumes way too much time already.

I should decide on a framework for this. And I should create it too. Even created and maintained by AI it must be human editable and maintainable. So this needs some experience and knowledge. However if someone really is interested in this and volunteers it's ok for me, too.

The next step would be to outline a concept of the new documentation. This would be best if two or three people would decide on that in a constructive manner. This does not necessary require a local AI client. Once it is defined I can feed it in.

If the concept and a rough TOC structure is established the hard work starts. Filling in the chapters by collecting all data from the old Wiki, verify it and create a new pages. This is the part that depends heavily on AI.

If the new docs fill up, part of PR reviews will be to check if there is a need to update docs. If the author of the PR can't do it because of the lack of AI, I can do it while reviewing. This should be ok.

---

Well, this is the rough idea. Even with AI it will be a huge batch of work. However I consider it doable with the help of AI. So it boils down to: One or two volunteer to tackle this, willing to spend next to a lot time also money on an AI subscription, or already having one. I am well aware this is a lot to ask for and I can understand everyone declining. But I wanted to give it a try 😄

[wthaem]

Thanks for launching this discussion. It is a matter of fact that the QMS documentation needs new ideas to revive it. In your text and in the AI supplement to it there are plenty of ideas/statements I would like to comment about. But this needs some careful thinking and some time.

A first comment: some of the parts you list as hand-written are created by me with help of scripts. But the scripts are never made public.

[wthaem]

Here are some additional remarks (English translation mainly created with Copilot):

• Preliminary remark: As justified and necessary as the desire to revise the documentation is, the amount of work involved is large—huge, even intimidating. This automatically raises the question of how this mountain of work can be managed. Sufficient human workforce available over a longer period is hardly in sight, so AI remains as a possibility to take over at least parts of this work. But how much can AI really take over, and doesn’t the use of AI also mean that human labor must be used to verify its results?

• Local changes vs. a well‑thought‑out new concept: I do not believe it is possible to achieve a satisfactory solution for the documentation solely through local changes, meaning changes to individual text passages on individual pages. Therefore, it seems appropriate to first look at the overall concept (AI can help here!), bring it to an improved state, and then create the content according to the new concept.

• My own contribution: I have increasingly less time available to contribute to the documentation. In addition, I am probably by far the oldest contributor to the QMS project. As a result, I would like to continue contributing to the documentation and I am able to do so, but I cannot take on any form of coordination for this project. However, such coordination by one or a few people seems absolutely necessary to me.

• Sphinx: At the beginning of my work on the documentation, there was only the wiki. I wished for an additional F1‑style help system for QMS. Based on my knowledge at the time, I suggested using the help mechanism employed by Qt. A major personal advantage for me was the supported full‑text search and the use of an index. In the meantime, Sphinx has become widely used as a software documentation tool. Out of personal curiosity, I once converted the existing documentation largely automatically into Sphinx format, and I am quite satisfied with the result. The much‑discussed navbar issue, which someone pushed through with great pressure years ago, resolved itself automatically here with appropriate configuration. Full‑text search is supported, and index creation is fairly simple.

• Index creation: I cannot imagine that the keywords required for an index can be meaningfully generated automatically. Keywords will probably have to be created manually and consistently. When using Sphinx, you do this directly in the text to be indexed.

• AI for automated documentation: From existing code, AI can certainly generate quite good documentation. For developers, this is certainly very advantageous. However, the documentation is meant less for code developers and more for QMS users. Users do not look much at the code; they look at the user interface and the actions possible there. I have no experience whether AI is capable of generating user‑oriented documentation from existing and highly structured code (but some quick tests have been neverthreless proising!). And the interface and its actions are unfortunately the part that changes relatively often and currently also makes the wiki appear quite outdated. So far, I have only worked with the free versions of ChatGPT and Copilot, so I cannot assess the differences to a paid version. In many cases, AI has helped me well and quickly in creating scripts, but in more than enough cases it has also completely failed and offered solutions as guaranteed correct and functional that were completely unusable. So you need a rather large grain of salt when evaluating AI suggestions.

• Pull requests: The previous wiki strategy "Everyone can edit" has worked quite well so far, since only a few people contributed and only a little. With pull requests, this process would certainly become somewhat clearer, but it requires someone (possibly several people) to approve these PRs.

• Style guide: A relatively uniform style and formatting is desirable when working on the documentation. Such things are typically regulated in a style guide. This should be available as early as possible and requires considerable effort to develop. Its application not only affects the documentation; its rules also have repercussions on the code and must be observed there as well. This initially requires a review of the texts used in the code. With luck, AI can be used to create such a style guide and then also to revise the code (I had a promising attempt to create a first draft of a style guide with AI).

Next a few comments concerning the AI part using some of its statements as headings:

• What we have today: The description may be correct, but this is about the offline help, and for me that is a by‑product. The main product is the wiki. Here I see the following question: today, internet access is considered to be available everywhere and at any time. Do we still need an offline extra edition of the documentation, or is permanent access to some form of online documentation sufficient? This would also make the existing QMS help browser unnecessary.

• No branches, so a large rework cannot be prepared quietly: An interesting remark that should be discussed. This contains, for example, the possibility—already discussed in the past—of maintaining version‑bound documentation.

• No robot, so nothing can ever check that a page still matches the program: This robot gives me headaches, because I simply cannot imagine it yet. How is the robot supposed to check whether the execution of an action on the interface described in the documentation by images corresponds to the program?

• Images: An image can say more than 1000 words. But how many images can and should one use? Images/snapshots unfortunately change faster than one would like.

• A production line is running inside a workshop that has none of the tools a production line needs. For me, this is incomprehensible AI prose.

• When pages were last touched: far better: 39 were edited this year This may be formally correct, but the counting method is not. A change to a page in one place may require changes to a number of automatically updated dependent pages (TOC, index, ...). AI could not recognize this.

• Hand‑written navigation bars, hand‑written table‑of‑contents lines: Incorrect AI assumption. Navbars are generated by script, TOCs can be generated by scripts, but are usually modified manually on individual pages.

• The pictures are the real problem. Agreed. This must be addressed.

• Menu structure — the 277‑line menu overview page can be produced automatically. This is already done. The bigger problem here: consistent wording in menus and documentation and even spell-checking.

• QMapShack to photograph itself: Interesting but hardly feasible suggestion. This is related to the idea of making QMS internals (data, algorithms, functions, ...) accessible via a scripting language and using QMS automatically.

• Need a small demo map, elevation data and an example project stored: A justified suggestion, but based on my experience quite difficult to implement.

Summary

• What should be discussed further

  • Establishing a strategy for how the documentation should be handled in the future
    • What form should the documentation take (Sphinx?)
    • Which software tools should be used for the creation of the documentation
    • How to be with the offline version of the documentation
    • Who can help implement this strategy
    • How should the future structural organization of the documentation look like
    • Which existing documentation parts are unnecessary and should be removed
    • Who will develop a style guide (dealing with terminology, British/American English, formatting, conventions, …)
    • Which text changes in the code will be required due to the style guide (e.g., consistent capitalization in menus, consistent terminology)
    • Is there a way to run automatically somehow a language file (i.e. the set of all texts in the code) against the style guide to identify weaknesses

• What stands in the way of the project, what remains unclear

  • Available human resources
  • Use of commercial/paid AI variants
  • Uncertainty about what AI and script‑based automation can and cannot do—both for rewriting the documentation and for maintaining it in the future

• How my own contribution can look like

  • Contributing to the creation of a style guide
  • Contributing to the development of scripts that automate workflows
  • Contributing to the revision of individual texts
  • but: no longer taking explicit or implicit overall responsibility for the entire effort or for major parts of it

[kiozen]

It's completely understood that you can't take the complete responsibility. In fact I think no one can. I want to get the work on the documentation more into the direction like writing code. Adding or filling chapters is a PR. If you change the code and this has impact on the docs you have to fix the docs withing the code PR.

But for that writing docs has to be human and AI friendly. I had a lengthy discussion with the AI and Sphinx really seems to be the best choice.

Summary by AI:

Our requirements are:

1. HTML5 as main output, served by GitHub Pages.
2. The offline help shipped with QMapShack, generated from the same source.
3. English as base language, translations produced by an automated process.
4. Writers are not developers. Minimal tooling, works on Linux, Windows and macOS.

Sphinx is the only generator that covers all four:

• Offline help. sphinx-build -b qthelp produces exactly the .qhp/.qhcp input for qhelpgenerator, which yields the .qch file that CHelp/QHelpEngine already loads today. No other mainstream generator has a QtHelp builder. The QMSHelp.qch blob currently sitting in the repo would finally be generated from source.
• Translation. sphinx-build -b gettext splits the text into paragraph-level msgids. If one sentence changes in English, exactly one entry goes fuzzy and only that paragraph has to be translated again. That is what makes an automated translation pipeline affordable and repeatable. MkDocs and Antora can only translate whole files.
• Offline search. Sphinx writes its search index as a searchindex.js script file, which works from a local file. MkDocs Material fetches a JSON index and therefore does not work offline without extra glue.
• Writers use Markdown. With myst-parser the source files are Markdown, not reStructuredText. Nobody has to learn rST.
• Structure is generated. Table of contents, navigation, per-page TOC and the index all come from the toctree. The hand-maintained Prev/Home/Next lines, the manual TOC blocks and AxAdvIndex disappear. That alone removes a large part of today's maintenance work.
• Installation. pip install sphinx myst-parser furo sphinx-design sphinx-intl, one command, identical on all three platforms. Only whoever builds the .qch additionally needs qhelpgenerator from the Qt tools.

On formatting: MyST plus sphinx-design gives admonitions, tabs, grid cards, figures with numbered captions, list tables and a glossary. Cross references are checked at build time, so a link to a removed section breaks the build instead of rotting silently.

End AI content.

This needs some groundwork to automate getting screenshots and animations. I already filed a ticket #1217 . And I would start a framework on my private fork, so we can play and test before this hits maproom officially. I would also like to experiment with automated translations. The challenge will be to keep this super easy, so everyone can participate without a headache.

I would suggest I do the ground work first. Then we test. And then we can start discussion on the new TOC structure. But it wouldn't hurt if you develop a strong opinion on that in the meanwhile.

[kiozen]

I spent some time to hack a demo. https://github.com/kiozen/qmapshack/tree/QMS-1217_demo

This is about how to take screenshots in a way that can be updated, when the UI changes. There is a small readme in doc/WRITING.md. It should be self-explanatory. 🤞 There are also 2 test pages. test.md has been done by me manually. load-a-track.md by the AI. Content of both is as valuable as dolores ipsum.

It has it's limitations. And probably still needs a lot of fine tuning. I did not review the code and let the AI do it's thing. This is just to collect experience and to find out if it is usable. One finding already: It will be impossible to capture everything with this, e.g. tool tips. Or mouse cursor based overlays.

This is why there is a manual mode, too. Of course this will be subject to getting stall. But the tool has suspect to find hand made images that might need review or attention.

The goal is to make that as easy as possible. The current code is good, but not perfect. It needs to be refined once we are confident that this might work for the future and is worth spending effort to refine and improve.

Just give it a try! Everyone welcome. Start with your own page to test.

[wthaem]

I gave it a try.

What I did:

• Compiled kiozen/QMS-1217_demo

• As usual under Windows, qmapshack.exe together with all required DLLs and other required files is located in a subdirectory of msvc_64 (bin in my case). Thus, nothing is loaded from the PATH environment.

• From this bin directory I called

  d:\QtProjects\QMS\QMS4Qt6\msvc_64\bin>d:\QtProjects\QMS\QMS4Qt6\doc\tools\shots.py -v --binary 
       d:\QtProjects\QMS\QMS4Qt6\msvc_64\bin\qmapshack.exe list
  

  in the hope to see a list of the work already done.

• The -v parameter shows

  d:\QtProjects\QMS\QMS4Qt6\msvc_64\bin\qmapshack.exe -platform offscreen -style Fusion 
       --no-splash --config C:\Users\WOLFGA~1\AppData\Local\Temp\qms-shots-4k_q052y\shots.ini 
       --font-family DejaVu Sans --font-size 10 --shoot D:\QtProjects\QMS\QMS4Qt6\doc\images --shoot-task list
  

  This seems to be ok. But I don't know if the INI file mentioned exists. I didn't create it. Should this somehow be added to the command-line? The shots.py help doesn't give any information about such a file or parameter. Adding a --config parameter leads to a parameter error.

• The following window pops up:

  

  The reason for this I don't understand. qmapshack.exe starts normally when called without any parameters. I don't know what a platform plugin is. A normal qmapshack start is possible, thus, i assume that there should be something like a feasible platform plugin. Does the offscreen variant require something not used with the normal qmapshack version?

• While writing this comment I had the idea to check Qt6 for additional platform DLLs and found qoffscreen.dll. Adding it at the proper location in the qmapshack folder I got the wanted information!

Here is the result I finally got:

Recipes — reference these as images/<id>.png in a page

  TrackColorMenu               The track colour submenu
                               preview: D:\QtProjects\QMS\QMS4Qt6\doc\images\_preview\TrackColorMenu.png
  TrackMenu                    Context menu of a track in the workspace
                               preview: D:\QtProjects\QMS\QMS4Qt6\doc\images\_preview\TrackMenu.png
  TrackOnMap                   The application with the map zoomed onto the track
                               preview: D:\QtProjects\QMS\QMS4Qt6\doc\images\_preview\TrackOnMap.png
  TrackProfile                 Elevation profile of the demo track
                               preview: D:\QtProjects\QMS\QMS4Qt6\doc\images\_preview\TrackProfile.png

Exposed widgets — a shot of one of these needs no new C++, just an id

  About                        The about box
  CanvasSetup                  Canvas projection and scales
  CoordFormatSetup             Coordinate format
  CutTrk                       Cut track options
  DetailsArea                  Area detail panel
  DetailsPrj                   Project detail panel
  DetailsRte                   Route detail panel
  DetailsTrk                   Track detail panel
  DetailsWpt                   Waypoint detail panel
  GisItemRate                  Rating and keywords
  InvalidTrk                   Invalid track point report
  MapIconSizesSetup            Icon sizes on the map
  ProjWpt                      Project a waypoint by bearing and distance
  SearchExplanation            Workspace search syntax help
  SetupWorkspace               Workspace behaviour
  TimeZoneSetup                Time zone and date format
  UnitsSetup                   Unit system and slope display
  WptIconDialog                Waypoint symbol chooser

I'll do a bit more tomorrow.

[kiozen]

I refined the tool a bit more. WRITING.md should explain all. If not it is badly written 😉

[wthaem]

My impressions after my first attempts at using the tool but not yet based on the latest version of Writing.md:

• I was able to build my first website without much trouble. This approach seems to be a promising one!

• As I thought about what I had done in the past and what I have to do in the future, a list of comments and questions immediately came to mind:

• I assume that the proposed approach should do as much image creation work as possible and not rely on always possible manual work in case of not supported features.

• There are many technical terms (e.g., qt_scrollarea_vcontainer, CTableTrk) unknown to a page author not being a developer. This needs some learning for a page author.

• How to define and restore demo data? Does this require a PR? How to handle various sets of demo data? Is it possible to use special INI and workspace files to adjust the GUI and the data used in it? Most likely, the documentation needs the use of different maps with different properties, different types of tracks, databases, ... If PR are necessary then there will be a workflow "page author -> developer -> page author -> refined version of PR or any adjustments -> developer -> page author". When writing a page, I have normally an iterative process, not only what concerns the text but also what concerns the images and their content and, of course, the data used to get the wanted result. I have still difficulties to understand how this iterative process can be handled if a data change needs a PR to get something implemented in the code before I can continue with the work on a page. Do I see this correctly?

• Snap user-defined rectangles on the GUI (might be discussed in the latest Writing.md).

• Give image scale ratio as input. My taken snaps are too large and, maybe, their size may depend on screen resolution of the used computer?

• qoffscreen.dll is not defined as a qmapshack.exe dependency (obviously a Qt feature) and therefore not automatically found and deployed. At least on Windows this DLL should be deployed together with all other files.

• How to select the GUI language? I got the German layout in the images because my system is German but I need English and, maybe, other languages if we keep the QuickStarts.

• How to snap several widgets at the same time to one image (might be discussed in the latest Writing.md)?

• --font-family DejaVu Sans --font-size 10: Windows 11 has as a font file with name DejaVuSans.ttf. What happens if this font is missing or not found under the fixed name on some system? How to change these parameters? I got some images without text (characters replaced with empty squares), no idea how and why.

• How to check if snapped image is still valid (might be discussed in the latest Writing.md)?

• What happens if moving everything to a different computer?

I’ll keep experimenting with the tool and will certainly have more comments, questions, and requests, but it’ll take some time.

[kiozen]

A lot of good questions. I try to answer them with some general explanations:

The goal would be to do all image creation with that tool in a way that can be replayed at any time. And thus updated with a reasonable effort. I am not sure if that goal is 100% reachable. For now I removed the function to attach any screenshot and to test for stall manual screenshots.

However I added scenarios. And the possibility of taking rectangular screenshots of scenarios. This won't cover everything, too. But quite another load of it.

In the end it will be a decision if we really need to do screenshots of every aspect. Or focus documentation on the most important stuff and provide the mechanism for that.

Documentation will be a PR in the future. The process will be less complex as for bugs and enhancement. If the snapshot tool lacks a feature in the process, a developer, most likely me, will add a commit to the documentation PR fixing it.

Data and maps: Configuration is already stored by chapter. Same has to be done for data. And everything will be in the repo. That said, you can't use full map sets. But you can use a small dummy tile and blanks to document map creation and handling. And there will be a baseline of data. So you do not have to add data to each chapter.

Also language, theme color, fonts need to be addressed. It would be cool to have the docs depending on the system theme. And it would be cool to have automated translations of the docs. But this can escalate in size and effort quite fast.

[wthaem]

@kiozen: I wanted to see a map and opened the dialog to set a map path. Here is what I got:

Is the path shown in this window correct? I don't see a map. And I don't like this path on my system.

[kiozen]

Data and maps per chapter are not implemented yet. There should be the OSM TMS map as baseline

[wthaem]

@kiozen: "Click a track on the map and a small row of buttons appears over it, in a speech bubble pointing at the track." - I did this after activating my map. Here is the result:

Not very nice! Ctrl+Shift+F9 gives the same layout. Comment: I changed from fullscreen to a smaller GUI size!

[kiozen]

you have to stick to the scenario. and the scenario is not highlighting the track. You can always verify if it is done right if you do "./shot.py chapter ". This must produce the same shots as you have done interactively.

[wthaem]

@kiozen:

you have to stick to the scenario. and the scenario is not highlighting the track.

I don't understand this phrase. Certainly, because I do not yet understand what a scenario is and how to handle a scenario. And there might be a second reason for my misunderstanding: A wrong interpretation of the scenario description due to missing preconditions for using the scenario. This brings me to my next remark:

Assume, I start a new page/chapter and I want some images in a form not yet used/implemented. As an example: I want some part of the GUI with special data (a user-selected region). Currently, I read:

### If it is not in the list, ask for it -> ok

Write the request as three lines:

- which page it is for -> ok
- what the reader has to see -> this is just the documentation text, isn't it?
- what you would do by hand to get there -> can be a lengthy story

I'm not sure if this will be an easy task. I take the image because it says more than 1000 words. And this step just seems to need the 1000 words, i.e., the precise and short description of what I want to see in the image can be hard work (it must be clearly understandable by the person implementing the scenario). In the mentioned example I even have to describe the exact location of the selected region on the GUI. But this location is bound to my computer and my system, isn't it?. How can it be reproduced on another system? Where is my misunderstanding?

Another remark:

The directory doc\shots\_cache is used to save tiles from online maps that I opened manually. Will this directory (or at least its tile cache part) be committed and then pushed to the repo? Most likely, no good idea.

[wthaem]

@kiozen:

Sorry for the stream of comments. Here is one more:

I run:

...\shots.py --binary .\qmapshack.exe -v chapter wt

and get:

qmapshack.exe -platform offscreen:configfile=C:\Users\WOLFGA~1\AppData\Local\Temp\qms-shots-qbgreut1\screen.json -style Fusion --no-splash --config C:\Users\WOLFGA~1\AppData\Local\Temp\qms-shots-qbgreut1\shots.ini --font-family DejaVu Sans --font-size 10 --locale en --shoot D:\QtProjects\QMS\QMS4Qt6\doc\images --shoot-task chapter --shoot-target D:\QtProjects\QMS\QMS4Qt6\doc\shots\wt.json
chapter failed with 3221226505 failures <===========================

wt is my new page on which I have some images taken with shots.py. How should I use this command correctly? The images and the shots directories are correct. The file wt.json exists. I didn't check the Temp directory.

[kiozen]

your way to call all of this is strange. Doesn't the recommended way from the WRITING.md work?

[wthaem]

@kiozen: what can I learn from the output of the subcommand list? The one help text says the widget classes a shot can build from nothing. I'm not sure if this text is correct: can a shot build a class from scratch/nothing? And even if so, can this info be of interest for a user of the Image shooter?

The other help text says windows QMapShack can photograph without you opening them. How do I photograph a window without opening it?

Are the widgets/classes listed in the output those where I can shoot an image? Certainly not.

[kiozen]

"list" is of no real use. I removed it. "explore" and "inspect" is for debugging. Also of no real use.

Generally speaking the items listed are named widgets that do not need a real scenario. e.g. The workspace setup dialog. The can be opened, their child widgets selected and you can take a shot of the child with ctrl+shift+F9

Everything else that needs preparation by UI interaction needs a scenario. e.g. expand the tree of a project.

In general scenarios are tricky. I spent most of the time to fix bugs to reproduce scenarios. And I am certain there are even more bugs. This whole automated screenshot stuff has it's limits. It's pretty annoying to find all the quirks and to find out what is possible and what is not possible. And I do not have a good feeling if it comes to stability when future code changes are done.

But never the less I do not see a way around automated, reproducible screenshots. If we drop it, documentation will go stall over time, because these shots are not easy to generate. You need to know the setup for each. However with the new tool it might go stall, too, because the tool gets broken and maintaining it takes too much time and effort.

So the question is still: Is it worth it? Are we able to write good documentation with limited screenshots from the tool? Surely a picture says more than 100 words. But many pictures together with 1000 words do not make a good documentation either. The trick is to explain the not so obvious in a few images and text. And leave out the obvious.

I pushed another batch of changes that hopefully address your findings.

[wthaem]

So the question is still: Is it worth it? Are we able to write good documentation with limited screenshots from the tool? Surely a picture says more than 100 words. But many pictures together with 1000 words do not make a good documentation either. The trick is to explain the not so obvious in a few images and text. And leave out the obvious.

I start liking the tool. Especially, after understanding what is hidden behind the former list subcommand. I can't believe that 100% of the images necessary for the docu can be taken with the tool. But quite many can be taken. This is an excellent feature. Development of the tool certainly must stop at some point. I believe you are close to that point.

Some/many(?) images can be taken manually and the will rarely change.

I think it is time to switch the discussion/development to other topics of the documentation project. Here I have in mind: which documentation framework to use (Sphinx+MyST+?, ...), structure of the docu, style questions, and some others. Answers to these questions are a prerequisite for writing text for the docu without revising it permanently.

I experimented a bit with Sphinx (RTD, furo, Qt output, ...). I pulled together a draft of a style guide. I use a test page when working with the image tool. Here can be my next contributions.

I pushed another batch of changes that hopefully address your findings.

Thanks! Helped a lot! Opens the way to take much more snapshots.

[wthaem]

@kiozen: let me raise a rather typical style question. This can help to understand how to deal with such things in the future.

You might have noticed that we use slightly different terminology: you prefer picture . I prefer image. I asked Copilot and the Microsoft style guide which word to use for software documentation. Here is the answer:

A picture is a non‑technical, real‑world photograph.
Used for photos taken with a camera, pictures of devices, landscapes, people, or anything outside the software domain.
It implies something informal or physical.
In documentation, picture is only appropriate when referring to a real‑world photo used as an example or illustration.

An image is a technical, neutral, format‑agnostic visual.
Used for screenshots, diagrams, icons, UI elements, figures, rendered graphics, plots, maps, and anything produced by software.
It implies a file inside the documentation system.
Image is the correct term whenever the visual is part of the software, UI, or documentation workflow.

You use picture not only in the tool code but also in its GUI. In my texts I traditionally prefer image. Obviously, the word preferred by the AI, too.

Now, there is a conflict which should/must be resolved. In any case, quite some changes are necessary either in text or in code. The GUI and its description (my variant of it) should use equal terminology.

What would be a good approach to resolve such terminology conflicts?

[wthaem]

@kiozen: for me one essential part is still missing in the Image shooter tool: how to insert and use some data (tracks, maps, dem, ...) necessary to get good snaps. Example: try to explain the various routing options without images or without suitable tracks and maps.

[kiozen]

Here is the plan:

• Add new fixture data to the tool. In the final version there should be map, dem, routing data, track, waipoint etc. And the possibility to add data per chapter. No clue how to do that, yet.
• The feature is right now on a demo branch. This means it is just created by AI, without reviewing. Just quick and dirty.
• The change is huge and needs some developer sub-tickets to port the changes from the demo branch into the stable code base
• The tool's UI and wording needs a review. I did not care for the demo and let the UI choose.
• There are still some unsolved issues. Mainly: The images do not match exactly when taken on different machines, different OS,
  different Qt version. This would constantly create changes in git. The repo will be bloated within a few months.

So this will consume my development time for the next weeks. And will stall any real documentation.

Imho Sphinx and all that is needed for it is already decided. If I want to have HTML pages as well as Qt internal help files, it is the best option. I just do not have any idea how to integrate that. CMake target? Independent Python script? No clue yet.

I am a huge fan of a style guide. But I have no real opinion on a style. Usually I am very pragmatic on such things and choose what ever is already defined. E.g. for the c++ formatting I used Google style. The important part: It must be possible to enforce it automatically. This is easy with code. Much harder with prose. Imho there must be a solution that can be done with any AI. Usually this works by having an MD file with the style guide, point the AI to it, remind the AI constantly to use it. And when reviewing a doc PR this has to be checked with AI. All possible. But a huge drawback for everyone writing docs without AI. However I do not really see any feasible alternative that can be done with reasonable effort.

If we prefer certain wording that must be defined in the style guide, too.

That leads me to the content of the new documentation. One general caveat of documentation:

No one is reading the docs.

Well at least not, if it is too much prose and it does not get to the point fast. I think this is the problem of the Wiki. It's a huge collection of trivial, important and outdated information. There are some gems hidden below quite a crust and thus hard to find.

So what is important information?

I am the opinion that most stuff in QMapShack is intuitive. Sure many will object. But let's be honest:

• Most actions are trivial and self explaining.
• There are many useful tool tips.
• Most complex features have a help text to guide the user.
• No huge toolbars or menu structures to get lost. Actions are shown when focusing an item.

Of course UX can be improved. Always. I think the UI has made a step forward the last year. This has to be continued. Better fix the UX, rather than trying to document bad UX.

So do we really have to document this trivial stuff? And if we do, has it to be presented in the front row? There is nothing wrong with a page that lists all actions with their icon and a short explanation. But there is no need to make it jump to the user on first sight.

So in general next to writing the docs from scratch we should also focus on:

• Reviewing the help texts in the UI
• Reviewing the tool tips
• Before struggling to explain a complex feature think about how to simplify it.

But if we do all of that, what's left to document?

Concepts - QMapShack has a few concepts that are very basic to understanding the app. e.g. the layers in the canvas and their draw order. The concept that the data of these layers is not linked to another layer, e.g. DEM not linked to maps, routing not linked to maps. Or the concept to focus items to get actions either by clicking or by context menu, etc.

Data preparation - We are not able to provide ready to go data. The perfect way would be how it is done for BRouter with the wizard. But we can't do that for maps, DEM, etc. I added some help lately withe the overlay stuff. But this will never be perfect and covering everything.

Workspace and database - This is probably a topic many new users struggle with. Other apps handle the topic different. For most users the constrains of a database are not obvious. They think in filesystems. And there are many non-intuitive constrains, e.g. data must be loaded from the database to the workspace to be changed. No direct change of data in the database (including some exceptions).

And probably many more. These are just the most prominent in my head.

Another idea in my head is to add help buttons wherever a complex UX is encountered, e.g. range selection. This button should open the chapter in the local help. But that requires code changes, etc, and is for later. Maybe it's a good point to keep in mind while structuring and writing documentation.

And the biggest challenge will be to write a good, easy to read documentation. I had quite a share on that using AI. Maybe it's just Claude Code, but AI tends to write excessive prose with a very overloaded style. It's lecturing, writing history lessons, start using it's own terms, guessing rather than facts, and hiding the point under a huge heap of blabla. And honestly, the wiki, written by humans, often suffers the same problem.

So it really boils down to identify the stuff that really needs documentation and to document it in just a few, simple sentences. Admittedly this is a huge challenge.

[wthaem]

Imho Sphinx and all that is needed for it is already decided. If I want to have HTML pages as well as Qt internal help files, it is the best option. I just do not have any idea how to integrate that. CMake target? Independent Python script? No clue yet.

From my CMake experience: There was an old copy script to collect all required files for the Windows version. I rebuilt this step and use now a CMake build project. Runs smoothly.

The Sphinx build is in principle a Make run with some parameters. The parameters involve the output type (HTML, Qt help, ...). This can certainly be implemented in a CMake run. What else should be included in this integration? Retaking all snapshots with shots.py? Can be included in the CMake run. Creating a PR? No idea, but you can certainly answer this question. There remains an unanswered issue: what to do in the case of warnings and errors. There can be plenty in the Sphinx build or the shots.py run.

I am a huge fan of a style guide. But I have no real opinion on a style. Usually I am very pragmatic on such things and choose what ever is already defined. E.g. for the c++ formatting I used Google style. The important part: It must be possible to enforce it automatically. This is easy with code. Much harder with prose.

Imho there must be a solution that can be done with any AI.

I don't believe that any AI can do this. I asked my Copilot and my ChatGPT if there is an API which I can use for this purpose. Copilot: no API at all. ChatGPT: API if you pay.

Usually this works by having an MD file with the style guide, point the AI to it, remind the AI constantly to use it. And when reviewing a doc PR this has to be checked with AI. All possible.

Possible yes. I submitted both the style guide and a Markdown file to my (simple?) AI and got some evaluation result (you may have seen it). But this was a manual process. My attempts to use AI to create or optimize code or text were not so convincing. Some times good, sometimes miserable. The result has to be checked manually. This is my experience.

So it really boils down to identify the stuff that really needs documentation and to document it in just a few, simple sentences. Admittedly this is a huge challenge.

Maybe, a proposal: I had again a look at the existing Quick start page. This page describes what QMS is, how to get and install it, how to launch it. It gives some initial ideas how to use it. And it is read! Check with GitHub! Why not taking a revised version of this page as the main page and supplement it by a few additional pages with more details for interesting and not so obvious topics: Installation details for various systems, interaction of workspace and database and device, use of routing engines, use of track filters, etc. This approach has more advantages: it is just one page. The revision can be done with a reasonable volume of work. It can be easily translated to other languages, too. The revision should include a clear hint to use the various forms of tooltips in the GUI (which need from time to time an improved wording).

[kiozen]

I pushed another update of the tool. As usual WRITING.md is the source of truth.

The update is now implementing the complete writer flow. The goal is to commit only those images that really change. So if you generate the test page on your Windows PC and publish, no images should be in the commit. As long as you did not change the shots via the tool.

[kiozen]

Yes, check against the style guide is a manual process. But it should be done by AI rather than a human.

And yes the quick start page is important 😄 But it's needs heavy rewriting. There is a lot of reading right from the start with a lot of information that a novice user will have a hard time to find out what is important and what to do.

But it's for sure a good start. Each section should get to the point in a few bullet points that have a visible gain for the user. It's ok to provide links into the more detailed chapters at the end of a section. In the beginning this will redirect to the online Wiki. And as time goes by into chapter pages of the new documentation.

This is really an experience that I have made the past few months working with AI. AI shits your screen with bloated text, trying to explain every detail at once and overloading the reader with many new terms and notions. If you have to read that 8h straight your brain starts to hurt. Funny enough if you insist to get to the point, AI is able to boil it down to just a few sentences. And from that point on you can ask for details if that was too brief. But in most cases that brief answer is what you wanted to see.

The Wiki is pretty much the same: bloated, very detailed. Hard to find out what's the point. In contrast I answered questions in a much more focused and condensed manner on the Naviboard and referencing the Wiki for more details. So same problem and pattern.

In the end this boils down to:

• What is the point of a topic? This should be the first the user is reading.
• What is the list of all aspects of a topic? Each one worth a chapter or a section in a chapter?
• Does it need a table, enumeration etc of all details?

And stick to single, short sentences or bullet points rather than on lengthy prose.

[kiozen]

Btw, I rework the tool again. Still not satisfied by the flow.

[kiozen]

Ok, rework done. I think that was in improvement, Writing.md is your friend.

One thing. The shot tool is now called

./shot.py page

no "doc" or other funny stuff anymore

[wthaem]

@kiozen: Comment to WRITING.md:

In part Seting up there is the following phrase: It is off by default and is never in a released binary.

Assume a Windows user wants to contribute to the docu. Then the quoted phrase implies that he must be able to build QMS and to pull together all files necessary to run QMS in the documentation mode. Or: For Windows and interested people a QMS documentation mode package must be distributed. Or: Include the documentation mode in the normal distribution.

[kiozen]

It's up to the package maintainer to decide if the screenshot feature is shipped or not.

Generally speaking this patch opens up a way to control the application remotely. Just by instinct I would say this shouldn't be available in a normal release.

Taken the contribution to the Wiki in the last years, only a few dedicated users contributed. And they have knowledge about how to compile.

Contributing to the wiki is really easy. With the new documentation a writer has to go thru a complete PR with review. So checking out the code and working on the markdown files will require much more knowledge. This will limit the group of contributors. However taken the experience for the last years this will not make much of a difference.

[wthaem]

@kiozen: Do I get the Publish idea correctly:

• The Image shooter tool (as I call it) can be used on different machines with different OS.
• Even if the scenarios and the image taking rules are the same on these machines the images taken can be different (fonts are rendered slightly differently, menus look different,...).
• Assume several people contribute to the same page on different machines.
• Therefore, it may happen, that a Windows user does see an image taken on a Linux system.
• Doing nothing with this image won't change it
• Retaking the image is possible and can even happen accidentally but it doesn't have an effect unless Publish is pressed. In that case the Linux image is replaced with the Windows one (assuming a commit and a PR follow).

[kiozen]

Yes this is roughly the process. The problem is that the screenshots even differ by pixel when taken with different Qt versions. Therefore the tool can't reliably determine if a shot did change because of code changes or just because of a platform change.

That is why a human has to decide if an image needs to be updated. So not too much of a difference compared to the Wiki. The goal is to make the job a bit easier and repeatable. Up today I can't say if that will be the case. It might turn out that the complete work, that went into the tool, did not solve anything.

[wthaem]

My own post prompted me to think further about the development of QMS and its documentation.

Here are a few general points:

• QMS is available for Linux, Windows, and macOS.

• Since the release of QMS version 1.21.0 about 3 weeks ago, the Windows version has been downloaded about 1,500 times. This user base is large enough to justify continuing to offer a Windows version in the future.

• Linux and Windows have different approaches to software deployment. On Linux, simply having qmapshack.exe may be enough to run it successfully. Windows requires that all DLLs and other files used be provided.

• qmapshack.exe is about 16 MB in size on Windows; the entire QMS installation requires about 400 MB.

• We are planning to revise the QMS documentation. It would be desirable for authors who work on Windows to contribute as well.

• A major new feature for the documentation will be the creation and maintenance of images/snapshots using a special tool that works with a specific version of qmapshack.exe.

• Question: So far, the name qmapshack.exe has been used for both the standard version and the special documentation version. Shouldn’t a specific name be used for the documentation version?

  If you keep the name of the default version for the documentation version, you'll end up with a second complete directory on Windows that's about 400 MB in size; if you use different names, you can simply add an additional EXE file to the existing directory.

• The use of the new tool must be described for the authors of the documentation. This is currently done in the file WRITING.md. This file is heavily developer- and Linux-oriented. Significant additions are required for potential Windows authors. For example, the brief notes on the build process and the build directory are sufficient and correct for Linux but not for Windows. How much developer language must a documentation author (a typical QMS user and not a developer) understand (e.g., the technical terms which describe the components of a widget)?

• Question: So far, only a few users have built the Windows version themselves. Should a documentation author be able to build the Windows version on his own, or should the version required for documentation be provided alongside the base version? The latter has the advantage for authors that they do not need to install MSVC, MSYS2, Qt6, etc., on their systems.

• Question: Is it absolutely necessary to have two different EXE versions, or is one EXE file — which can or must be launched in different way — sufficient?

• Additional question: How can we ensure that all authors are describing the same development stage (release - dev - commit #)? Use of Sphinx metadata?

• Additional notes on WRITING.md:

  • The uppercase filename caused some issues in Sphinx. Can it be changed to lowercase?

  • In addition to the ![]() syntax for inserting images in Markdown, MySt also supports the directive

    :::{figure} ../images/page_name/img_name.png
    :alt: alt_text
    :name: image_name
    :scale: 30%
    :align: center
    
      Caption text
    :::
    

    This directive has several advantages (e.g., caption, image scaling,...). It works seamlessly with shots.py, and could therefore be mentioned as well.

[kiozen]

Before we start to discuss another peculiar process to satisfy Lex Microsoft I would like to explain my point of view on how documentation should be done.

From the experience of several projects in the last years I came to the conclusion that code and documentation must live together in the same repository. And that developers have a strong responsibility to write and maintain documentation. That does not exclude anyone just writing documentation. But it puts both parties under the same constrains.

The constrains are:

• Documentation is always written for the latest state of the code in the repository.
• Documentation is updated and committed together with code changes.
• Documentation is released together with the code.

This is the only way to keep code and documentation in sync. And it demands much more commitment from the developers and the writers. But the benefits are obvious: The user always has the matching documentation for their version of the software. And responsibilities are clearly defined. "You change the code, you have to fix the documentation. It's part of the PR."

Therefore checking out the repository, compiling the code and using the locally compiled version of the application is a fundamental part of this process. I know this is quite a hurdle. Especially for the writers. But I do not know any other process that keeps the documentation in a good shape unless there is a dedicated full time writer involved.

So the question is more: Is there a way to enable any Windows user to compile QMapShack from the repository without becoming an expert first. One answer is using a container (docker etc). Another an (interactive) build script, that does all the downloads and updates and the tweaking of the build system etc. With today's AI support a feasible task without becoming an expert on scripting.

[kiozen]

Ok, that took a while but now the tool is in a PR

#1267

As usual WRITING.md is the source of truth. I did a lot of testing but I am sure there are still a lot of glitches to find. Please add any findings as comment to the PR.

The next 3 weeks I will have limited time to work on this and to response. So be patient. 😉