Strange non-standard layout for command documentation?
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
Strange non-standard layout for command documentation?
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'.
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 (67.98 KiB) Viewed 1928 times
Re: Strange non-standard layout for command documentation?
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.
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 (14.41 KiB) Viewed 1916 times
Re: Strange non-standard layout for command documentation?
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Strange non-standard layout for command documentation?
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.
Re: Strange non-standard layout for command documentation?
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>
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Strange non-standard layout for command documentation?
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
-
- Veteran
- Posts: 2611
- Joined: Tue Feb 21, 2012 8:07 pm
- Location: Torino - Italy
Re: Strange non-standard layout for command documentation?
Ulrich1a created this macro https://forum.freecadweb.org/viewtopic.php?p=238344
unfortunately it is not used.
Re: Strange non-standard layout for command documentation?
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.
I sort of agree. But vocx also has a point.
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.
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.
Re: Strange non-standard layout for command documentation?
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}}
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>
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Strange non-standard layout for command documentation?
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.