yorik wrote: ↑Fri Oct 26, 2018 4:50 pm
I also think you should do a more detailed "plan", that is, (like you started already), identify topics you think you could work on, and put some goals, like, in XX weeks you plan to have done X and Y, etc. I don't doubt that with a good plan the vast majority of people here will agree to fund you.
I basically spent two full days looking into the wiki and documentation to see how it all worked, so this is my proposal.
1. I feel there are two needs, (1) documenting the usage of FreeCAD, and (2) documenting the programming aspects of FreeCAD, either for advanced users (scripting) or for developers. What is more important? Or what is a pressing matter?
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 would look into the main page of each, say,
https://www.freecadweb.org/wiki/Arch_Module, look into every single tool, for example,
https://www.freecadweb.org/wiki/Arch_Wall, and add or improve the information there. A big portion of the job would be to add links to relevant and useful pages. That is, add links to Draft Wire, Draft Line, etc., if mentioned in other pages. This will help with making the wiki more user friendly, because it would be possible to jump to different tools quickly.
3. Navigation tools are needed. As was noted in the other thread
https://forum.freecadweb.org/viewtopic.php?f=21&t=31876 I think navigation boxes are useful, because they help you go to the specific workbench that you want fast. Ideally, every workbench should have a navigation box with the tools inside of it, so that if you are looking at the Arch Workbench, you can immediately jump to other tools inside that same workbench, without going back to the main page of that workbench.
4. Translations are important. It is not my objective to complicate the translation effort of the software. As was mentioned in another thread, using templates a lot would mean creating a translated template for each language which is cumbersome.
https://forum.freecadweb.org/viewtopic. ... 17#p265217 I believe this shouldn't be too complicated for simple templates, as there are around 20 main languages for which makes sense to have translations. Of course, speakers of other languages should do the work to maintain their own languages when it cannot be quickly automated.
I believe the more successful a project is, the better it is at receiving translations. So let's make sure the project has good documentation and then we'll see an increase in popularity, and then surely it will get a lot of translations.
5. Physical documentation and printing. I am not sure how good the PDF version of the documentation is. Is this created entirely from the wiki? A wiki guideline says that there shouldn't be too many repeated information because then printed documentation would have the same information repeated many times.
https://www.freecadweb.org/wiki/WikiPag ... Guidelines
This is something that worries me if using navigation boxes, as I expressed in point 3 above. Are navigation boxes also included in the documentation? I wouldn't like this in a printed document, but I like it in the online version.
6. I am not sure what to do with the application programming interface documentation, C++ and Python APIs. Is this supposed to be generated automatically with Doxygen and placed in
https://www.freecadweb.org/api ? Then why does it appear as well in the wiki? Was the API documentation in the wiki placed there manually, before Doxygen was implemented? If this is the case, I believe we should use only one place to put this information. Remove the information in the wiki, and use only Doxygen, or the other way around.
This thread sheds some light on the matter
https://forum.freecadweb.org/viewtopic.php?f=21&t=31824
This is on the wiki
https://www.freecadweb.org/wiki/Category:API
This section contains obsolete data, and is in the process of being transferred to autogenerated API documentation on
http://www.freecadweb.org/api
In the wiki, I modified and introduced a couple of templates that make looking at the API better on the eyes. See for example,
https://www.freecadweb.org/wiki/Draft_API for functions, and
https://www.freecadweb.org/wiki/Base_API for classes, and
https://www.freecadweb.org/wiki/Object_API for properties.
The templates are
https://www.freecadweb.org/wiki/Template:APIFunction function with description, and return value
https://www.freecadweb.org/wiki/Template:APIFunction_b function without description, nor return value
https://www.freecadweb.org/wiki/Template:APIClass class with description
https://www.freecadweb.org/wiki/Template:APIClass_b class without description
https://www.freecadweb.org/wiki/Template:APIProperty property
But still I don't want to touch this more because I don't want to do duplicate work if you are actually in the process of building much better documentation using Doxygen.
On the other hand, a simple scripting guideline to use a tool is documented in the tool itself, for example, look at Draft Line
https://www.freecadweb.org/wiki/Draft_Line The command (makeLine) is documented there. The same function signature is in
https://www.freecadweb.org/wiki/Draft_API
Having two points with the same information should be avoided. Should the first page (description of the tool) direct to the API? Should the API have examples at all? Or only a listing of the functions available? They should have links to each other, which is exactly what wandererfan did with the TechDraw API pages, he put links back to the user documentation.
https://www.freecadweb.org/wiki/TechDraw_API
But at the same time, wandererfan put examples in the API section. Most of those functions are strictly programming functions that can't be used from the GUI, so that's the reason they aren't described in the user documentation. But others like
https://www.freecadweb.org/wiki/TechDraw_SaveSVG are described in both.
What I would do is describe the tool in the tool page itself (say, Draft Line) and also add a link to the API page, both the wiki and the Doxygen generated site (
https://www.freecadweb.org/api).
By the way, the APIFunction templates that I mentioned above are okay for C++, but aren't okay for Python, because in Python you typically specify the default arguments with an equals sign as described here
https://www.freecadweb.org/wiki/Python This equals sign breaks the wiki's {{template}} system which does substitution of parameters with that sign.
7. Fix page naming. I suppose in the past workbenches were called "modules". All workbench links actually point to a page with _Module in the name. And I guess all redirections redirect to these. This is confusing to the user, so they should go to
https://www.freecadweb.org/wiki/Draft_Workbench, without being redirected to
https://www.freecadweb.org/wiki/Draft_Module
Would this be a titanic task? Would it break translations? Translated pages could be copied and pasted into a new correctly named workbench. But the current translation system doesn't allow direct edits, so I'm not sure about this.
8. Fix tool page naming. I think each tool should be named in a reasonable manner, like [Workbench]_[Tool]. This is included in the Wiki guidelines
https://www.freecadweb.org/wiki/WikiPages#Structure In many cases this is respected (Draft Line, Draft Wire), but in others, the name of the page sort of refers to the icon. For example, the tool
https://www.freecadweb.org/wiki/TechDraw_NewArch should probably be named "TechDraw_ArchView". Adding "New" to the name is confusing. Obviously it creates a "new" ArchView, but this makes it hard to refer to the tool with the proper name.
"Please check the [[TechDraw NewArch]] tool" works but it sounds strange if I include this in a tutorial.
"Please check the [[TechDraw ArchView]] tool" sounds better, but doesn't work because the page doesn't exist. I could use a redirection, or just rename the original tool page, and change all links that point to it accordingly.
Again, the same problem. Would translations break?
A problem that I see is, again, the repeated information. For example, there exists both
https://www.freecadweb.org/wiki/PartDesign_NewSketch and
https://www.freecadweb.org/wiki/Sketcher_NewSketch They both refer to essentially the same tool, a Sketch. So, maybe "PartDesign Sketch" should just point to "Sketcher Sketch" (which doesn't exist at the moment).
9. Redirections. I love them. It's a simple way of fixing things and making explanations fluid were it makes sense. But I'm not sure if other wiki administrators are fine with it. I don't think redirections take much space in the server, but my impression from the other thread is they aren't happy if I use too many redirections.
Let's say a tool is strangely named "A". So I create a page with a better name "B", which redirects to "A". All user pages are changed to use "B" (the redirection), instead of "A". Ultimately I move all the information into "B", and delete "A". Would that work? Would translations break?
Okay, so these were my observations. Now with a timeline.
10. Timeline. I think the easiest is to go workbench by workbench.
Week 1: planning stages in forum, organization of tasks
Week 2: document the Draft workbench
Week 3: document the Arch workbench
Week 4: document the TechDraw workbench
Week 5: document the Part workbench
Week 6: document the PartDesign workbench
Week 7: document the Sketcher workbench
Week 8: (week to finish documenting pages that weren't finished on time)
Week 9: revisit the tutorials, update old tutorials, add new tutorials
Week 10: whatever is needed, after feedback in the forums
The first week of planning is what we are doing right now, discussing with the interested parties, and planning, so that when I start editing pages, people are satisfied, and won't protest too much. Of course, if people don't have many comments, I'd just start working on the Draft workbench immediately.
By documenting, I mean clicking on every single link of the workbench, making sure the {{GUICommand}} template is correct, making sure the information is correct and up to date, adding links, fixing broken links and redirections, adding navigation box, adding API code when necessary, cross-referencing the information with the API by Doxygen and github, adding categories to the page, and minor tasks like that. I'll also post in the forum every day to inform everybody about the progress of the documentation, and to get feedback if there is something that users would like to see.
About the tutorials, I could try to recreate and update some tutorials that were created for 0.16 and earlier versions, so that the instructions work with the more recent 0.18 version. I recently finished a new tutorial
https://www.freecadweb.org/wiki/Tutoria ... en_windows so part of my experience with the wiki stems from writing that, and finding the links to the workbench tools. I believe by writing tutorials, it becomes immediately apparent which workbench tools require better documentation.
Each week should be paid USD 100. So, after ten weeks, you would have paid USD 1000. Of course, if you are generous, you could put a bit more, as you say there is almost double that in the pot. Personally, I'd like to be paid all at the same time, say, USD 1000, by week 6, so that it makes sense money transfer-wise and so I can fill my taxes accordingly. Of course, this is subject to review. If you think the documentation job is not okay, then we can end the job there.
Of course, this is all in regards to user documentation. Is user documentation a priority over API documentation? Or is API documentation (the source code) more important? Because if that's the case, then I'd have to go into the C++ and Python sources, and that's a bit more of a complex task, which is more of the domain of the core developers, because they are the ones who are able to describe better how each piece of code works. I could try above all correct the docstrings of the Python files sources because that is markedly easier.