On Documentation Quality

[ediloren]

I have been studying FreeCAD some months now, learning, reading, watching, compiling, using and modifying, as I am testing it for using as front-end for our EM software (see http://www.fastfieldsolvers.com).

I started contributing to the documentation with the small experience I had collected so far. I would like to point out some issues that can be corrected, and share and get your opinion on some other topics.

First and most notably, “Get Involved” on the main page points to the old (deactivated) SourceForge wiki (http://sourceforge.net/apps/mediawiki/f ... lp_FreeCAD) . It should point instead to http://www.freecadweb.org/wiki/index.ph ... lp_FreeCAD (I have of course no way to change this link).

A similar but more subtle issue is present on the documentation page. Pages are wiki, but the documentation menu bar on the left cannot be changed / updated. Therefore it is not following the same structure as the documentation wiki, and this is quite confusing in my opinion, especially for newbyes. Either we find a way to let people update it, or as a “quick win” I would remove the structure from the left bar and leave only the entry points to the main, most immutable topics. I would recommend:
- Manual ToC
- Users hub
- Power users hub
- Developers hub
No subtopics.
I see that the same issue was pointed to on viewtopic.php?f=10&t=3899 but with no result apparently. My proposal may be a bit crude but would iron it out.

I would also recommend however, on my side, to open a self-standing Forum folder about documentation. I know there are the talk: pages, but as normandc points out in viewtopic.php?f=10&t=3899 , nobody (almost) uses them.
So I join surfin_eddie and wandererfan opinion in that I would appreciate a common single place to discuss changes and improvements to docs, since not all can feel the same, especially for somehow disrupting proposals, as the previous one. So before touching major structures of the pages, I would appreciate a discussion in a proper place. I feed that this cannot be the wiki directly, that is instead good for summarizing the results, but would require a dedicated discussion folder on the top of the Forum, i.e. http://forum.freecadweb.org/.

A couple of points I would also like to touch, that would be well addressed on a self-standing discussion, are for instance:

- how to link the documentation to a specific FreeCAD version. This is key for quality improvement and to evolve from a permanent work-in-progress job to a solid product.

- On ‘Help Freecad’ page http://www.freecadweb.org/wiki/index.ph ... lp_FreeCAD I would add a link to the discussion page http://www.freecadweb.org/wiki/index.ph ... =WikiPages. As already pointed out in the Forum at viewtopic.php?f=8&t=3988&start=10|, discussion on the help / docs is scattered around. This page http://www.freecadweb.org/wiki/index.ph ... =WikiPages is a tentative to have an organized ‘how-to’ on improving documentation. However this page is very rough as of today, that’s why I think it is worth discussing before modifiying the wiki adding the link.

- ‘Getting started’ page is not really a getting started at all IMHO. When I approached FreeCAD first I got a bit frustrated because I could not get the gist of it, and the program crashed every step. So two issues here: the first is that the newcomer should get a feeling quickly about what he can do, even if the example is trivial in itself. The second is that, no matter how tested the SW is, if a user wanders into seldom-used cases, the probability of a crash increases exponentially (we all tend to perform operations in the same way once we have learned an acceptable way to do them). So as done for other SW, I would completely rework the ‘Getting started’ from a plain description of the meaning of the icons present in the main workbenches to a simple / some simple ‘tutorials’ showing how to achieve a result in FreeCAD. I think that a very clear and simple structure for FreeCAD tutoriasl is the one used on FreeCAD tutorial - Unofficial tutorial blog by Adrian Przekwas (I added the link in the wiki). The tutorials in this case are not basic at all, but are very effective. But again, I am shy performing this change before having had some brainstorming / discussion. You may think differently.

I appreciate your opinion!

Enrico

[yorik]

Hi,
Glad to see your proposals. I hadn't seen the other topic you link to, it was apparently during my holidays, I missed several posts.
I fixed the link on the homepage already. FYI the homepage is on https://github.com/yorikvanhavre/FreeCAD-homepage

For the forum section dedicated to the wiki, I find this a good idea... I'll open one.

For the sidebar, I've been looking at a solution to make it translatable (and therefore editable by non-admins) but still didn't find out how to do that efficiently. But I kind of agree with you.

For the rest, yes, all those "primary" pages (getting started, features, etc...) need a good revamp IMHO. For marking things like "available in 0.14" I had made some templates to add in the text:
http://www.freecadweb.org/wiki/index.ph ... te:Version but it was never used much and also needs better styling.

[ediloren]

Thanks Yorik - btw I was starting to think that I chose the wrong title for my post - other posts were getting hot while mine looks probably more boring I should have titled it something like "SolidWorks feature parity almost achieved" as a booby trap and then keep the same content

In the meanwhile I worked on http://www.freecadweb.org/wiki/index.ph ... =WikiPages to split it in two, with the intention to summarize in the first part some general structure and style guidelines, and in the second part to keep the existing brainstorming, waiting for the dedicated forum section.

My idea is to keep it as much simple as possible (but not simpler than that ), and at the same time give some consistent guideline.
It is work in progress of course, and everybody is welcome to contribute, but of course your opinion since your role and project seniority has more weight (whatever you say..), as well as of course normandic, jrigel, etc. (sorry if I don't mention all)

I will go on crunching through the docs, so see you again in the dedicated forum section, and thanks for the hint about the main page being on github (so far I just used the frozen 0.13 sources).

Enrico

[ediloren]

Another proposal for a quick win.

I'm a practical guy, I know most of the people would not want to read a full style guide, so I'm trying to keep it short and simple. But even better than that, I am putting in front the example section. If a picture is worth 1000 words, an example may be worth 500 words, so even if people just use the same structure and style of the 'best practice' FreeCAD docs page, we are well ahead of a consistent contribution from the documentation writers (of course again I'm not speaking about content here).

However, while I already have a good example of a command doc page (as referenced on the main http://www.freecadweb.org/wiki/index.ph ... lp_FreeCAD), i.e. " The Std_ViewScreenShot page is a good example of what every other command should like" I sorely miss other best examples (for instance for Workbenches, etc.). I can pick some myself, but I would gladly have your input on this, since it should be easy for you to point to what are in your opinion some good pages for every category.

Thanks
Enrico

[NormandC]

Hello Enrico,

I was starting to think that I chose the wrong title for my post - other posts were getting hot while mine looks probably more boring

Truth is, there was a lot of discussion about this a few months ago, and if anyone else is like me, they were probably not interested in going over this all over again. The topic must be somewhere in Open discussion.

Problem is the wiki was unavailable to North Americans for a full four months. They changed host not long ago. Even if it's fully back online now, I was so totally disgusted with the situation (and still am) that I lost all motivation to contribute to it or even talk about it.

[yorik]

I hope you'll change your mind Norm, the wiki behaves just perfect now!
I didn't follow that other post unfortunately, that was when I was in holidays. I'll move it to this forum so it's easier to find it later.

I think some pages could already be passed to the new translation system... They recommend to do that only with pages that are
stable enough so their structure won't change much, but I think several pages are in that case.

I also found a way to translate the sidebar, but it requires to create one separate little page for each item of the sidebar. So maybe ediloren's suggestion to remove all the doc links and keep only entry pages like user hub, poweruser hub, etc... makes sense? OTOH I kind of like being able to jump right to the doc I want from the sidebar...

[ediloren]

Hi Normand,

I understand your frustration. However, not having to start all over again every time is exactly one of the main points of my intervention.

Before even thinking to contribute to the Wiki, I tried to dig out all the information of what had already been done - I think this is the only sensible thing to do for a new member. You can see I made reference to some posting, and the dedicated Wiki pages I found on the topic.
If you want further proof, see first line: I know how to correctly spell your name

But the issue here is that I found this information scattered all over the place. So I was trying to contribute first of all making some order, not re-inventing the wheel. That's why I am proposing a dedicated forum section, so at least all discussion is in one place only, plus the links on Wiki on how to write pages in the wiki.

BTW I also was hit by the tail of the wiki downtime - I asked for membership since end of July and had to wait September - I was starting to wonder if there already were so many contributors that one more was not useful - but Yorik was supportive and I appreciate that; after all, as they say, s**t happens.

I would really appreciate if you old members could at least provide a hint for the "quick win" I proposed: some well written, well formatted pages to be used as references.

On the index topic, foillowing further input from Yorik, I agree is good to be able to jump directly to a topic, but only if the index and the sidebar are aligned, otherwise this only creates confusion IMHO. I must say that I find FreeCAD not very intuitive (and seeing feedbacks on SourceForge other casual users think the same); this is anyway ok for me, because it is a complex software; but documentation in this case should help clarifying 90% of the doubts, and having a confusing docs structure creates frustration in my experience.

Cheers
Enrico

[ediloren]

Wow when I posted the reply I automagically found myself in the new forum section!

Well done Yorik!

Ciao
Enrico

[ediloren]

Now that we have a dedicated forum section, with no risk to jeopardize the document related discussion, I will split my points one per topic.
Discussing more than one topic per forum topic (!) is dispersive.
I am already forking the discussion on the index, see 'Table of Contents'.

I would still gladly keep this topic for the main quest for documentation quality; and therefore for receiving your pointers to well written wiki pages.

Thanks
Enrico

[NormandC]

I hope you'll change your mind Norm, the wiki behaves just perfect now!

Yeah, and it took 5 months.

4-5 months ago I was willing, eager, desperate to put in some time into the wiki. Right now I don't give a damn.