Hi,
I am setting up a training for QField users which covers both Cable packaging and QFieldCloud synchronisation. New users and even experienced ones will visit the Get Started pages and the How-to Guides when familiarising themselves with QField or when they run into an issue. And in my opinion they should do this, that’s what those pages are for.
Therefore I also use the descriptions in those pages as input for the training.
Following the instructions pretending I am new to QField I noticed room for improvement. Sometimes very basic and important steps are missing, sometimes instructions in both pages contradict, sometimes it is not clear what an instruction is actually for, etc.
In this thread I will post these improvements when I run into them as replies, instead of creating a topic for each one. I would love to see replies improving or correcting my improvements and possible a reply if an improvement has been implemented in the Get Started or How-to pages.
2 Likes
Improvement 1 - Duplicate steps in Get started chapter QFieldSync
https://docs.qfield.org/get-started/tutorials/get-started-qfs/
The sections Package for QField and Synchronize from QField are duplicated in this chapter.
The only difference between the duplicates is the styling. The first time they appear as Workflow box, the second time, after the section Additional Properties, they appear as plain text. The content however is exactly the same.
My suggestion is to remove the duplicates and to put both sections at the end, so after Additional Properties.
As for the question which version to remove, I like the workflow boxes style, but this chapter is a mix of workflow boxes and plain text without clear consistency, so I leave that to someone else.
Improvement 2 - Broken link in Package for QField section
https://docs.qfield.org/get-started/tutorials/get-started-qfs/
Step 3 in the (first) Package for QField section (workflow style) has a link to the Storage section, but this link is broken. The link in the duplicate (plain text version) Package for QField section is working correctly.
Improvement 3 - Add note to Packaging action Copy for copying the entire source file
https://docs.qfield.org/get-started/tutorials/get-started-qfs/
In the Layer Packaging section of the QFieldSync Get Started chapter the different options are explained. The Copy option is:
Copy (only available for file-based layers (eg. Gpkg, Shp, Tiff)): The layer will be copied to the packaged project folder but not be tracked. A new copy in the packaged project folder will be made.
A remark (may be a Note box or Important box) should be added that the new copy is a file based copy, not a layer based copy, which means that if you have a single layer from a multi-layer geopackage the entire geopackage is copied to the packaged project folder.
Even better would be to include somewhere in this chapter the good practise of manually creating a (or multiple) geopackage(s) with all layers in a designated project folder. This prevents copying all layers to the folder by QFieldSync. Currently, this practise is not mentioned at all in the entire Get Started page.
Improvement 4 - Upgrade the QField Sync chapter to Cable Packaging chapter
https://docs.qfield.org/get-started/tutorials/get-started-qfs/
Reading the QFieldSync chapter in Get Started, it seems more and more this is basically only about using Cable Packaging: the Layer Packaging options described are the four Cable Packaging options, the third and final step in the section Package for QField is about copying the whole folder on your device, and the Synchronize from QField is about copying the project folder from your device to your computer.
In comparison the QFieldCloud chapter has it’s own descriptions of the settings in QFieldSync (Advanced Setup chapter), although it does reference the QFieldSync chapter in the QFieldCloud Get Started chapter. I do think this reference is incorrectly used there, see a later improvement on that.
Improvement 5 – Add both sync options to Principles
https://docs.qfield.org/get-started/concepts/
QField is based around two main concepts of synchronization: Cable (manual syncing) and Cloud (more or less automatic syncing).
I think the documentation on QField would benefit from adding these two main synchronization methods to the Principles chapter. The can then reference to the relevant chapters in Tutorials. See Improvement 4 on the missing chapter (or naming) of the Cable option.
Improvement 6 – Choose different naming for Packaging the project as a GeoPackage
https://docs.qfield.org/how-to/project-setup/storage/#packaging-the-project-as-a-geopackage
The Storage chapter in the How-to Guide has an annoying ambiguity in naming steps.
Step 1 is about preparing a QGIS Project for use in QField. You can store all files in a designated folder OR you can “package the project as a GeoPackage”.
Step 2 is about copying the project over to the QField target device.
Here is where things get ugly:
The very first step in Step 2 is literally “Package the project either on the computer or via QFieldCloud.”
What exactly does this mean, considering the user has already packaged the project in Step 1? You can see where this goes wrong.
Because I think this step (2.1) is actually referring to the Package for QField action within the QFieldSync plugin.
If you do not do that, and try to transfer either the ‘designated folder’ or the GeoPackage in which the project was packaged, tour project will not function properly in QField. For instance it does not have the special log tables.
So I think this How-to will greatly improve from a better distinction between ‘packaging the project as GeoPackage’ (step 1) and “Package the project either on the computer or via QFieldCloud.” (step 2.1)
Dear @Jeroen-GroeneBij Thank you very much for these recommendations.
This page has been on my agenda for quite some time. Please be patient, as we are currently working on a new set of guidelines on writing documentation which includes the usage of the right terminology and vocabulary throughout the documentation.
Meanwhile, what I can recommend to you also is to raise your points as issues in GitHub - Documentation Issues.
This gives the documentation team a good indication and motivation to address these points.
In any case, I will create an issue on GitHub and thereby address the points.
Best regards,
Berit
