Strange non-standard layout for command documentation?

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
Roy_043
Veteran
Posts: 8450
Joined: Thu Dec 27, 2018 12:28 pm

Strange non-standard layout for command documentation?

Post by Roy_043 »

Looking at these pages I am seeing a layout that is quite different from the standard:
Std_SetAppearance
Std_SetColors

I am not sure if this was discussed somewhere, if so then I have completely missed that.

I imagine that the layout was changed to save vertical space.
But several problems are introduced. The main issue is that something goes wrong with the list indentation to the right of the image. And IMO it is also not a good idea to deviate from the standard. It is the standard (WikiPages#Examples) that ensures consistency (per workbench and across workbenches).

BTW: I would use 'Context menu' instead of 'Contextual menu'.
Attachments
Std_SetAppearance.png
Std_SetAppearance.png (67.98 KiB) Viewed 1928 times
User avatar
Roy_043
Veteran
Posts: 8450
Joined: Thu Dec 27, 2018 12:28 pm

Re: Strange non-standard layout for command documentation?

Post by Roy_043 »

Another issue is the updated image on the Std_SetAppearance page.
If you compare the new image to the old one you will notice that the frames in the task panel (not 'task dialog') are almost invisible in the new image. This is an issue related to the styling used on the Windows OS.

To create images of dialogs/task panels with frames you have to rename \bin\styles\qwindowsvistastyle.dll and restart FreeCAD. I know this results in an 'older' look, but having the frames clearly visible is more important.

Cropping the image so that the Close button is not visible is also strange IMO.
Attachments
Std_SetAppearance_taskpanel.png
Std_SetAppearance_taskpanel.png (14.41 KiB) Viewed 1916 times
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: Strange non-standard layout for command documentation?

Post by vocx »

Roy_043 wrote: Sun Aug 02, 2020 8:08 pm ...
I am not sure if this was discussed somewhere, if so then I have completely missed that.
...
Always notice the date of creation of the page. There are various wiki pages that were created a very long time ago, like in 2013 or so, and back then the wiki looked different, and probably was more inconsistent. A big part of the wiki also seems to have been migrated from SourceForge, so occasionally you'll find in the source of the page many manual line breaks <br/>, which should be removed, of course.

My advice is that if you see big inconsistencies like this, you change them to the more modern appearance.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
User avatar
uwestoehr
Veteran
Posts: 4961
Joined: Sun Jan 27, 2019 3:21 am
Location: Germany
Contact:

Re: Strange non-standard layout for command documentation?

Post by uwestoehr »

Roy_043 wrote: Sun Aug 02, 2020 8:37 pm Cropping the image so that the Close button is not visible is also strange IMO.
The Wiki is there to provide info one needs to understand a feature. Every dialog has such a button, most also OK , Cancel etc. This is nothing we need to provide. Also have in mind that not everybody has a big screen. Saving informationless space helps to keep the pages readable without much scrolling.

In general I am not a fan of the screenshots of dialogs because they are not translatable. So from my perspective we don't need these images at all. The description of its content should be sufficient. But since they already exist, I kept it.

Besides this, I don't understand that a page was an orphaned nobody cared about for 6 years is now a big deal for a general style discussion. I took care now and updated it. The important thing is that users understand what this feature is about. Since the FaceColors is part of the Part WB, I changed it to fit into the layout of the other Part WB pages.
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: Strange non-standard layout for command documentation?

Post by vocx »

uwestoehr wrote: Sun Aug 02, 2020 11:10 pm ...
In general I am not a fan of the screenshots of dialogs because they are not translatable. So from my perspective we don't need these images at all. The description of its content should be sufficient. But since they already exist, I kept it
...
Images are extremely helpful for newbies to really understand the use of the command. Not everybody is comfortable reading walls of text; images just make the documentation of higher quality and more user friendly, although obviously it is a pain to maintain in good shape, as if something in the GUI changes the image may no longer be correct.

In an ideal world, translators would take a screenshot of the translated interface and add it to the translated page. This is the reason most images are also set to be translated. The more people join the documentation effort, the easier it will be to maintain this.

Images that don't need to be translated can be skipped by using the appropriate tags around the image.

Code: Select all

</translate>
[[File:Image_does_not_need_translation.png]]
<translate>
With dialogs there is no way to avoid text, but for other images, I try to add images without any text, and only a description of it in the caption below.
Last edited by vocx on Mon Aug 03, 2020 8:08 am, edited 1 time in total.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: Strange non-standard layout for command documentation?

Post by vocx »

uwestoehr wrote: Sun Aug 02, 2020 11:10 pm The Wiki is there to provide info one needs to understand a feature...
I didn't realize you had modified the page before the changes that I made, and that you reverted.

Here is the explanation that I give in the talk page.

Our guidelines, WikiPages, clearly say that we should not use the caption inside the image. This makes them not easily translatable. It's better to translate the text separately. This is how it's done in most other pages that I have modified (many thousands). The caption is always separate from the image. In the past this was inconsistent and many pages had the caption inside the image, and many others had it outside; now we try to be consistent and always add the caption outside. As I say in my previous post, for images that don't need to be translated we can surround the images with the tags to de-activate translation before the image, and re-activate it after the image. We also discourage floating images, this is hard to handle. In the past there were a few floating images, and many pages were littered with unnecessary {{clear}} templates to stop them from floating. It's better to be consistent with the vast majority of pages and not make exceptions, even if the results are less than you would like.

It's unfortunate that you have a small screen in your laptop but you should not make decisions based solely on your situation. FreeCAD is fundamentally a desktop application, so it is expected to be used in a desktop computer with a monitor most of the time. What would be helpful is for you to investigate ways to make the wiki pages display better in different screen sizes and systems (tablets and phones); unfortunately the wiki hasn't received a lot of maintenance over the years so surely there are many improvements that could be made, not only to the information but to the administration of the mediawiki software.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
renatorivo
Veteran
Posts: 2611
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: Strange non-standard layout for command documentation?

Post by renatorivo »

uwestoehr wrote: Sun Aug 02, 2020 11:10 pm ... the screenshots of dialogs ... are not translatable.
Ulrich1a created this macro https://forum.freecadweb.org/viewtopic.php?p=238344
unfortunately it is not used.
User avatar
Roy_043
Veteran
Posts: 8450
Joined: Thu Dec 27, 2018 12:28 pm

Re: Strange non-standard layout for command documentation?

Post by Roy_043 »

uwestoehr wrote: Sun Aug 02, 2020 11:10 pm Every dialog has such a button, most also OK , Cancel etc. This is nothing we need to provide.
I disagree. If you create a screenshot of a dialog box or task panel it should not leave out essential buttons. Doing so can cause confusion.

uwestoehr wrote: Sun Aug 02, 2020 11:10 pm In general I am not a fan of the screenshots of dialogs
I sort of agree. But vocx also has a point.

uwestoehr wrote: Sun Aug 02, 2020 11:10 pm page was an orphaned nobody cared about for 6 years is now a big deal for a general style discussion.
The Std_SetAppearance page is not an orphaned page. I have worked on that page quite recently. Your changes to it surprised me (OK I admit: I was annoyed). But style and standards are important. There are things I do not like about the proposed standard, yet I feel that it would be wrong to not follow it.

vocx wrote: Mon Aug 03, 2020 2:29 am Our guidelines, WikiPages, clearly say that we should not use the caption inside the image.
I cannot find that on the page. Perhaps you are thinking of a different page? Note that this 'caption inside image' solution is used for the workbench icon on the main page of each workbench.
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: Strange non-standard layout for command documentation?

Post by vocx »

Roy_043 wrote: Mon Aug 03, 2020 7:37 am I cannot find that on the page. Perhaps you are thinking of a different page? Note that this 'caption inside image' solution is used for the workbench icon on the main page of each workbench.
I realize that WikiPages has been modified a lot since last time I saw it. I hadn't looked at it in months, perhaps the information is different now, but captions outside of images was a de-facto standard that I was applying, mostly for translation purposes. Since essentially nobody but me was modifying the wiki, I probably never stressed this with anybody else.

The "caption inside the image" is something that I fundamentally opposed, as was described in a previous discussion with Kunda, Please do not do this: </translate>{{incode|...}}<translate>

Essentially, images should have the caption outside the image, so it can be translated by the regular means.

Code: Select all

# stop translating here
</translate>
[[File:Example.png]]  # The image is the same in every language
<translate>  # Restart translation
{{Caption|This is the caption of the image, that should be translated by the translators}}
Adding the caption to the image means that you will have to "translate" the entire image together with its caption.

Code: Select all

<translate>

[[File:Example.png|This is the caption of the image, that should be translated by the translators]]  # The image will always be included in the translation even if it doesn't change.

</translate>
Or if you escape the text, you get ugly nested syntax.

Code: Select all

# stop translating here
</translate>
[[File:Example.png|<translate>This is the caption of the image, that should be translated by the translators</translate>]]  # You have to activate the translate tag and deactivate it again.
<translate>  # Restart translation
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
User avatar
Roy_043
Veteran
Posts: 8450
Joined: Thu Dec 27, 2018 12:28 pm

Re: Strange non-standard layout for command documentation?

Post by Roy_043 »

vocx wrote: Sun Aug 02, 2020 9:37 pm Always notice the date of creation of the page
Sometimes you are too much of a teacher. In this case you are a teacher who doesn't follow his own advice: you have not looked at the history of the pages before making your edits. They certainly do not help this discussion. Words like 'fundamentally' are also best avoided IMO. This is a discussion about the wiki, not some religious debate.

@uwestoehr:
In the revision history of the Std SetAppearance page you say 'float text around image for better readability'. But with the loss of list indentation, and the loss of clearly visible frames in the image, you have achieved the opposite. Even if we do not agree on the standard, I hope you can agree on that.

I would also be interested in hearing from more experienced wiki contributors and wiki moderators. Please chip in.
Post Reply