Wiki procedure?

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
Roy_043
Posts: 1883
Joined: Thu Dec 27, 2018 12:28 pm

Wiki procedure?

Post by Roy_043 » Wed Jan 29, 2020 10:18 am

I am just starting to look into this whole BIG Wiki 'thing'. I am wondering about 'procedure'.
How can you find out where documentation is lacking?
How do you know if some other user is already working on pages you have set your sights on?

@Kunda1 is giving status reports:
https://forum.freecadweb.org/viewtopic.php?f=23&t=42501
https://forum.freecadweb.org/viewtopic.php?f=23&t=42500
How should they be interpreted? As a ToDo List?

User avatar
kaktus
Posts: 247
Joined: Sun Aug 11, 2019 11:59 am
Location: opolskie
Contact:

Re: Wiki procedure?

Post by kaktus » Wed Jan 29, 2020 3:43 pm

Hello.

Messages of this type could also be linked in this subforum.

For example, I don't have so much free time to read the whole forum... which is a pity. :roll:
But this information is very important to me.

When preparing documentation in Polish, I see that a lot of documents are incomplete or outdated. :(
wierny padawan mistrza arturromarr
Twórca polskiej wersji Wiki dla FreeCAD.
"Cierpliwym być musisz, by wiedzę zgłębiać tajemną, gdyż ciemna strona mocy niszczącą i silną jest".

david69
Posts: 333
Joined: Wed Jan 01, 2014 7:48 pm

Re: Wiki procedure?

Post by david69 » Wed Jan 29, 2020 4:26 pm

hi,

when i want to translate, i start to check this page. i have bookmarked it.
https://www.freecadweb.org/wiki/Special:LanguageStats

note as French, i put fr for Language code. Just adapt to your language.

fyi, from any wiki page, on the left side, you've got many links.
you scroll down at the very bottom and if you click on "special pages" then you have that page
https://www.freecadweb.org/wiki/Special:SpecialPages

and here, you have "language statistics" under Data and Tools.

i think Kunda is only listing pages requiring up-date and improvment only for Draft workbench. my minterpretation is well a ToDo list.

to know, who has worked on a page, click on history of each page and you'll see who, when what has been modified.

hope it helps.

vocx
Posts: 5206
Joined: Thu Oct 18, 2018 9:18 pm

Re: Wiki procedure?

Post by vocx » Wed Jan 29, 2020 8:32 pm

Roy_043 wrote:
Wed Jan 29, 2020 10:18 am
...
How can you find out where documentation is lacking?
How do you know if some other user is already working on pages you have set your sights on?...
The only way to really know what needs to be documented better is to go through each page manually.

When I started using FreeCAD, I wanted to build a house, so I looked up the Draft and Arch documentation, and worked through some examples, and learned to use the software that way. Then I decided that the documentation was just not good enough. So I committed myself to improve things.

I started with Draft, and basically tested each command in the Draft Workbench page, making sure that each worked as described, and if not, I would improve the text, images, examples, and code. Not only did I test the graphical tool, I also went into the source code, and little by little started understanding it. This is helpful in order to write better documentation, as you can explain why things work the way they do, and the limitations.

Essentially, one thing leads to another, and to another, and to another. That's how a wiki works. It's a collection of interconnected pages. So, when you start reviewing one page, it leads you to another page, and perhaps this could be written better, so you improve it, and then you go back to your original page, and then a second link leads to another page that you could also improve, so you do it, and this has more links, so you continue, etc. You can get lost in a rabbit hole pretty quickly, but that's how it has to be done.

My original intention was to improve the Draft and Arch documentation. But I noticed a lot of issues that could be tackled at the same time, tutorials on using tools, so I wrote them, organization of the tutorials and video tutorials, how to use the GuiCommand template more effectively, how to organize the pages more effectively using Categories, the obsolete nature of the API, etc.

I finished going through the Draft tools, but I actually never started reviewing the Arch tools in a similar way. There is just so much to do.

So, my advice is to just pick something that interests you, but be very committed to it. I would go through each and every command of each workbench, making sure the documentation is up to date with the current behavior. Along the way I would fix many small things, like using example images to show the behavior, using better templates to fill the information of the properties, providing code examples, etc.

Kunda's lists are just to show all pages in a workbench, in order to incentivize people to look at them, and maybe improve them. But we need committed users that are tenacious and willing to work on them for months.

----

You can't really know if somebody else is working on a page. You just have to monitor the history of the pages to see what has changed recently. In the upper right, there is a Watchlist link which shows you all pages to which you have contributed that have received changes. This allows you to check periodically the information on pages which you have modified in the past.

All of this is done without clear organization at the moment. As I said many times, we just need more users. Once we have enough users, then small teams will form organically to coordinate tasks better, in the case of the wiki, to do better edits and maintain a certain style. Right now, we just need to add more information to the wiki, in order to attract more users to the software, who eventually will become power users and developers.

I think two priorities exist, and that is (1) to update the old documentation (a lot of pages exist but haven't been updated significantly in years), (2) improve the status of the power user and developer documentation. Unfortunately, for the second point, this has to be done by users with enough experience with FreeCAD, particularly with scripting and workbench writing. That is, this has to be done by developers. Unfortunately, developers like to develop new code and not write documentation. Somebody needs to bridge those two tasks.
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
Posts: 5206
Joined: Thu Oct 18, 2018 9:18 pm

Re: Wiki procedure?

Post by vocx » Wed Jan 29, 2020 11:24 pm

Now I just want to touch on the topic of translations.

It seems to me that from the early times, there were not many native English speakers working on the documentation. Pages were written in English, but often by people whose main language is German, French, Italian, Spanish, etc. This resulted in many pages being strangely written. Such is life. Then with the translation plugin of the wiki (Localisation), it became easier to translate pages. This requires writing good English pages that can then be translated relatively easily by translators.

There is a significant problem if you make a lot of changes to the English page. If you do this, many translations in the other languages will be lost, and will have to be written again. In the past, NormandC used to patrol the wiki, and he absolutely disliked breaking translations, because understandably he had put a lot of time into them (French). So, it was very difficult to advance the English documentation pages for fear of breaking translations.

Fortunately, or unfortunately, depending on your viewpoint, NormandC decided to take a pause from the FreeCAD community, so he was missing for most of 2019. This allowed me to re-write and make significant changes to the English pages without worrying too much about translations. I maintain that to get a good omelette you have to break some eggs, so I think breaking the translations is fine, as long as the resulting product is much better than before. Moreover, it seems translators don't really mind, and they are quick to translate again the most common languages, which are French, Italian, and German. We really need more translators for other big languages like Spanish, Russian, and Chinese.
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
Posts: 1883
Joined: Thu Dec 27, 2018 12:28 pm

Re: Wiki procedure?

Post by Roy_043 » Tue Feb 11, 2020 1:55 pm

Looking at the history of pages I see that some contributors seem to favor making, sometimes the same, minor changes to many pages. Most pages I have checked have been updated in this manner over the past two weeks. I now get the idea that whatever I start modifying will conflict with somebody else's plans. How should I deal with this?

I would personally prefer to 'claim' a (related) set of pages, with {{Page in progress}}, and then try to bring them completely up to date.

vocx
Posts: 5206
Joined: Thu Oct 18, 2018 9:18 pm

Re: Wiki procedure?

Post by vocx » Tue Feb 11, 2020 4:36 pm

Roy_043 wrote:
Tue Feb 11, 2020 1:55 pm
...
I would personally prefer to 'claim' a (related) set of pages, with {{Page in progress}}, and then try to bring them completely up to date.
I think in the past weeks Kunda has been doing this sort of automated cleanup using the wikibot. I haven't used the wikibot because I've concentrated in writing and not in small repetitive tasks like those.

Truth is, there is no process to claim pages, but you can very well announce it here, and people would respect it, I'm sure. It's not done now because, well, there aren't many people working on pages at the same time. The chances of somebody modifying your pages at the same time is minimal. They could be translated, but that doesn't affect your original content.

Another alternative is to write the pages as you want in a sandbox, meaning that you create a page exactly as you want, but don't make it public yet. You can prefix it with your name or something like that, say, Roy:PartDesign_Workbench. Once you are satisfied with its content, then you add the entire information into the real page, PartDesign Workbench, and you remove the sandbox page.

As I said, we just need a bigger group of users willing to participate consistently in writing documentation. If you have proposals on how to organize this better then feel free to come up with plans and ideas. I haven't done it because being too strict does not incentivize collaboration. At this point we take all the help we can get.
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
Kunda1
Posts: 8386
Joined: Thu Jan 05, 2017 9:03 pm

Re: Wiki procedure?

Post by Kunda1 » Tue Feb 11, 2020 10:34 pm

Sorry, I know it's frustrating but we need to the wiki pages to have a uniformity that is still missing. Hopefully by then end of this big round of edits we 'will all be on the same page' cheesy pun intended.

List of goals trying to complete:
  • Migrating away from all the FreeCAD command PNG icons to SVG file format.
  • Adding icons in front of their wiki page names
  • Linting templates (making them more readable)
  • Filling out missing variables in {{GuiCommand}} templates I.e. SeeAlso: and Version:
  • Separating category templates from each other so they get translated separately
  • cleaning up categories by going in to their translation pages and appending the correct countrycode to said template: {{GuiCommand}} to {{GuiCommand/it}}
  • removing superfluous categories that are already added through templates. {{Userdocnavi}} already added [[Category:User Documentation]] to the page. no need to add it again
  • Fixing typos and grammar
  • Formatting keyboard shortcuts like {{KEY|Ctrl}}+{{KEY|C}}
  • Adding {{TOCright}} (outside of translation tags) to pages that need it (this moves the Table of Contents box to the right of the content.
  • Renaming 'How to Use' sections to 'Usage'. This way it easier to reference sections in a wiki page via the URL Draft Clone#Usage
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features

vocx
Posts: 5206
Joined: Thu Oct 18, 2018 9:18 pm

Re: Wiki procedure?

Post by vocx » Tue Feb 11, 2020 11:10 pm

Kunda1 wrote:
Tue Feb 11, 2020 10:34 pm
...
[*]Filling out missing variables in {{GuiCommand}} templates I.e. SeeAlso: and Version:
...
I only wonder about this. These two fields are optional.

I think it's good practice to always add something to SeeAlso, but it is not required. If the entry is not given, nothing will happen. Maybe we should provide a default link?

The version information is nice to have, but again, it's optional. This option was added recently, I think a year ago, so we can only really know the version of new commands introduced around 0.17 to today. If this is not given the template will just print a dash -.

I guess we could enter the version and the dash manually, at least to make sure every template is using all variables.

Code: Select all

{{GuiCommand|
...
|SeeAlso= [[Default_page]], [[User_hub]]?
|Version=-
}}
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
Posts: 1883
Joined: Thu Dec 27, 2018 12:28 pm

Re: Wiki procedure?

Post by Roy_043 » Wed Feb 12, 2020 9:16 am

Kunda1 wrote:
Tue Feb 11, 2020 10:34 pm
Sorry, I know it's frustrating
Without further information on what has been finished I will have to wait.
It would help if you perform the tasks per WB and report which have been done.

I would not mind jumping in. Might be a good way to learn. But again I would need more information.

Post Reply