Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

[NormandC]

so I believe some hard decisions will have to be made

The problem is that the few people who could make those decisions are so overwhelmed that they don't even have time to read this topic, and the 2-3 other topics where we are going about this back and forth. And just like always, even if a decision would be reached, only a tiny group of people will end up having to do the work. (I'm writing this while I should already be in bed)

[vocx]

vocx wrote: ↑
Tue Oct 30, 2018 5:29 pm
About translations. Yes, it does sound like a problem. But, oh well, I think breaking a few things to improve others on the long term isn't such a bad investment.

Again, who will do the work? As usual, the same handful of guys. How much time would things remain broken? Weeks? Months? Years?

About translations, I think really the only solution is the community. I believe FreeCAD still hasn't reached that critical level of popularity in which translations gain momentum and are self-sustaining. As you have mentioned, only a few dedicated users have translated French and Italian. This to me indicates it's probably "okay" to break translations now, establish a good documentation system now, so that FreeCAD obtains a much better reference manual for the future. Later on, once the program has gained that necessary traction, then at that time will translators jump into the project, without feeling that it's only a small number of people doing the job. I understand if you don't agree with this, but still I appreciate what you say as you've definitely been around. I always find it funny when you say, "I'm not a developer". By now you should!

[chrisb]

I'm always for cleaning things up. If you change contents in the documentation then translations have to follow, no doubt about that. If you make rather technical changes, you have to consider if it is really improving the situation. If you really want to make things cleaner you have to go through all of it including source code and translations.

In this case we might have to be rather pragmatic than being perfect. The few translators (besides french and italian) should rather translate contents than to fix things.

[yorik]

I'm quite happy with your plan vocx.

Couple of details, mostly repeating what Normand says:

- Indeed translation is a delicate matter. The system we use on the wiki is far from perfect, but it's basically the only translation plugin that works well, and we should indeed reserve templates mostly for when it's translation-independent (like {{KEY}}, etc), or only when it's absolutely needed.

I am not sure how good the PDF version of the documentation is. Is this created entirely from the wiki?

This is something we tried at early stages, but it's definitely not practical, our wiki has evolved to a point it cannot be represented linearly anymore. I would 1) concentrate on keeping the manual linear. The manual would be the only part that gets converted to PDF. 2) Some pages of the wiki could be included in the PDF, but they would be pulled by some other structure. The navigation system shouldn't be used anyway.

I am not sure what to do with the application programming interface documentation

I'm not sure either. I'd be more in favor of keeping the small examples inside the wiki pages, but for the general API pages and all the rest use the doxygen one, which we definitely must make look better and clearer. I don't see any reason why we shouldn't be able to get to the same result as the current API pages of the wiki.

I suppose in the past workbenches were called "modules".

A module is an application extension (we're talking about code, basically). A workbench is a special functionality of FreeCAD. Most of the FreeCAD modules also define a workbench with the same name, but not all (the Addon Manager is an example of a module that doesn't define a workbench).

I would suggest, in the wiki, to use the word "Workbench" everywhere it is possible, which will be 99% of the cases. It makes more sense for the user. That is basically what we've been doing for some time. We should check what still links to the _Module pages but I guess it's not much. I'd be in favor of fixing what's still _Module, but if you do so please also crawl through the existing translations and fix them accordingly (when possible, that is. Sometimes it requires someone to really know the language)

I think each tool should be named in a reasonable manner, like [Workbench]_[Tool].

As Normand pointed out, the page naming should follow what's defined in the FreeCAD source code so the "what's this?" system works. Note that it is always possible to change things in the source code too if needed.

About redirections, some love them, some hate them I don't have a strong opinion on this, but indeed the practicality of translations should really be considered there.

As Normand says, very few people do all the hard work on the wiki, most of them are in this thread and the other. Translators are also very sparse and tend to do big amount of work during a few weeks then disappear forever. So we should take some care to, as much as possible, not destroy the work they've been doing, so others are encouraged to extend it. On the other hand, I think the work you are proposing is very welcome, and indeed it will require a few groundwork changes. So it would be a for you to assess and limit these heavy changes as much as possible.

Generally speaking about your proposal, I think your plan is good, very sound, and to me worth the money and I think we should do it. I would propose to assess your work for example after 3 weeks and after 6 weeks, to make sure everybody is happy about it.

I'll ask the opinion of the most active community members privately, but anyone is free to give his/her opinion here too.

[vocx]

- Indeed translation is a delicate matter. The system we use on the wiki is far from perfect, but it's basically the only translation plugin that works well, and we should indeed reserve templates mostly for when it's translation-independent (like {{KEY}}, etc), or only when it's absolutely needed.

Understood. Now that I understand the difficulty of using and translating templates, I think it's okay to not define more than already exist.

I am not sure how good the PDF version of the documentation is. Is this created entirely from the wiki?

This is something we tried at early stages, but it's definitely not practical, our wiki has evolved to a point it cannot be represented linearly anymore. I would 1) concentrate on keeping the manual linear. The manual would be the only part that gets converted to PDF. 2) Some pages of the wiki could be included in the PDF, but they would be pulled by some other structure. The navigation system shouldn't be used anyway.

Just to clarify, are you saying I shouldn't use https://www.freecadweb.org/wiki/Template:Userdocnavi ?

Or do you mean the old fashioned https://www.freecadweb.org/wiki/Template:Docnav ?

I'd like to continue using Userdocnavi, as it's a nice way to jump around the tools in the online wiki. This makes sense to me, unless you can update the left sidebar, as discussed in the other thread https://forum.freecadweb.org/viewtopic. ... 57#p265957

But just to clarify, I have no intention of changing the user manual at all https://www.freecadweb.org/wiki/Manual:Introduction I think it should stay like it is. Maybe I'd just look for small corrections here and there, but nothing major. I wouldn't include the navigation templates in the user manual.

I am not sure what to do with the application programming interface documentation

I'm not sure either. I'd be more in favor of keeping the small examples inside the wiki pages, but for the general API pages and all the rest use the doxygen one, which we definitely must make look better and clearer. I don't see any reason why we shouldn't be able to get to the same result as the current API pages of the wiki.

Okay, I'll leave the API to the end, as for that, proper blocks of comments need to be included inside the actual source code of FreeCAD. That's a tough task on its own. I'll focus on the user documentation, that is, the wiki, first.

...
I would suggest, in the wiki, to use the word "Workbench" everywhere it is possible, which will be 99% of the cases. It makes more sense for the user. That is basically what we've been doing for some time. We should check what still links to the _Module pages but I guess it's not much. I'd be in favor of fixing what's still _Module, but if you do so please also crawl through the existing translations and fix them accordingly (when possible, that is. Sometimes it requires someone to really know the language)

Actually, plenty of pages use the _Module convention. But it's all handled with redirects. Basically, most _Workbenches redirect to the corresponding _Module page, everywhere on the wiki is like that. Very old pages seem to use _Module directly though.

I think each tool should be named in a reasonable manner, like [Workbench]_[Tool].

As Normand pointed out, the page naming should follow what's defined in the FreeCAD source code so the "what's this?" system works. Note that it is always possible to change things in the source code too if needed.

Okay, I think most tools don't have to be renamed anyways. It is not a problem in any case to keep working on what is currently available, and then see if it makes sense at all to do a change.

So we should take some care to, as much as possible, not destroy the work they've been doing, so others are encouraged to extend it. On the other hand, I think the work you are proposing is very welcome, and indeed it will require a few groundwork changes. So it would be a for you to assess and limit these heavy changes as much as possible.

Yes, heavy changes will be limited. Mostly maintenance, completeness, correctness of information, and internal links will be done.

Generally speaking about your proposal, I think your plan is good, very sound, and to me worth the money and I think we should do it. I would propose to assess your work for example after 3 weeks and after 6 weeks, to make sure everybody is happy about it.

I'll ask the opinion of the most active community members privately, but anyone is free to give his/her opinion here too.

It sounds fine. I'll post on the wiki daily to comment on the progress.

[sliptonic]

2. I feel I could dedicate myself full time to the first task (1) documenting the usage of FreeCAD, particularly the most used workbenches like Arch, Draft, Part, PartDesign, Sketcher, and TechDraw.

I really think the Path workbench needs to be included as well. The forum section is used heavily indicating a lot of users and many of the users are entirely new to FreeCAD.

[vocx]

2. I feel I could dedicate myself full time to the first task (1) documenting the usage of FreeCAD, particularly the most used workbenches like Arch, Draft, Part, PartDesign, Sketcher, and TechDraw.

I really think the Path workbench needs to be included as well. The forum section is used heavily indicating a lot of users and many of the users are entirely new to FreeCAD.

I haven't used Path Workbench myself, so I don't have a good feeling of what is missing that needs to be explained better. I have glanced over the pages and the tools seem to be sufficiently described, but yes, they could use a bit of cleanup. Path scripting has some examples, and Path Walkthrough for the Impatient seems to immediately show users how to do things. I will review these as time permits.

[chrisb]

The walkthrough has to be adapted to the changes made in 0.18. It's not too much, but at least the Job creation has changed.

[vocx]

The walkthrough has to be adapted to the changes made in 0.18. It's not too much, but at least the Job creation has changed.

I presume this is noted in the forum in different posts, right? So I'd have to go through some threads, to get this information to transcribe into the wiki.

[chrisb]

I will update the wiki for the walkthrough for 0.18 (if I don't forget it).