On Documentation Quality

[ediloren]

Another idea about good pages; I think it would be really helpful and educative to have both good and 'bad' examples for the same page, like for the Arch Wall here. Hoping nobody feels blamed, I think this would clarify the concept.

Maybe we can freeze both pages (the 'good' and the 'bad' examples), moving them in another namespace; so history is not there (no blame), nor subsequent modifications, which are useful to keep alignment with later FreeCAD releases but nobody guarantees that are still aligned in style.

Enrico

[yorik]

I did some work on the "getting started" page http://www.freecadweb.org/wiki/index.ph ... ng_started
I propose to remove all the list of commands below, it is from a time we had so few commands we were very proud of them Now there are too many to be meaningful...
I propose, instead, to give a few typical user cases, like how to import a step file, how to use the partdesign WB, how to use the Arch WB, etc... What do you all think?

[bernd]

I'm a new user. I've never used freecad before. I even have never used one of the mechanical cad systems (solid works, cattia, inventor, ... ) because I'm structural engineer. The CAD I know are Nemetschek Allplan and of course like most people standard AutoCAD, but mostly from 2D-drawing.

It took me a few hours to realize how things are put together in freecad. It was very helpful to go through these getting started page by page. I did not read the pages about python stuff, NOT YET. My opinion is first I need to work with freecad before I can start scripting.

I ended up again and again and again open the sample files at the startpage of freecad (schenkel and Architectural). After I tried some things modells where missed up. So close freecad, open freecad, open example file and start again. I did two video tutorials. They are gread but they do not show you how things are put together. More Information about the Modeltree in the Combo View Window would be better in my opinion. All the icons and toolbar change if one changes the workbench. This was really confusing at the beginning. The combo window is the only one which keeps unchanged.

bernd

[NormandC]

CAD in general is very complex, and parametric CAD like FreeCAD even more so.

What's worse, some workbenches have totally different work flows. The Sketcher/Part Design combo is so different from other workbenches it's as if it was a separate software in itself. When working with Part Design to model a part, it produces a Model tree completely different than with other workbenches. With other workbenches the tree shows a group of objects that you combine together. With Part Design, it shows a history tree detailing all the successive steps to create a single part.

All this is very confusing and we have yet to find a way to document this properly. I initially wrote the Part Design workbench page and the Sketcher workbench page. Some have said it is too long and dabbles in theory too much. Yet in my own opinion it is nowhere near enough. For example nowhere do we explain the complex concept of feature history. So where do we go from there...

Enrico has asked repeatedly here to indicate which pages should be considered "good pages" but in blunt honesty, I don't think any of us knows for sure (apart from the visual layout, use of colors), or has the same opinion. Which is why I haven't answered that question because I don't know anymore.

I would say to any who's interested to read the wiki pages topic where we had a lengthy discussion. I believe Enrico already read it.

All the icons and toolbar change if one changes the workbench. This was really confusing at the beginning.

In my opinion the alternative (all the toolbars shown at once) is worse. Although I guess anyone who's a SolidWorks fan would disagree . You can switch the GUI to the "complete" workbench but IMO it is a bad idea and in my view it should even be purged from FreeCAD. It is a mish-mash of tools handpicked from the most used workbenches and it is utterly confusing. You've got Part Fillet and Chamfer along with Part Design Fillet and Chamfer, tools which seem to have duplicate purposes but which are slightly different. You've got the Draft 2D tools and the Sketcher tools, and they have similar icons but colored differently. It is not clear which toolbar belongs to which workbench. It may be confusing at first to work with separate workbenches, but I think in the long run it should give the user a better understanding of each tool purpose...

Sorry for the off topic.

[yorik]

Indeed, it's been years that many people worked on this wiki, and we still didn't reach something really good. Another of the problems is that inherently software documentation made of a wiki is hard to browse, see for ex. the blender wiki, which is much more advanced than ours. Definitely writing good documentation is VERY hard.

At least things are bettering over time...

[NormandC]

I'm wondering if a mix of text and embedded screencasting videos wouldn't be more helpful. "Leveraging" (gah I hate that PR buzzword but have no alternative in mind at the moment) the full multimedia experience that the Internet can be.

Of course that would require even more work, and disk space - unless the videos are hosted on YouTube. The sound track if any would need to be translated, or have screen caption...

Another possibility would be to add a few animated GIFs, but too much can be an eyesore...

[ediloren]

Yorik, yes I noticed you updated the getting started page, as a matter of fact I was in the wiki doing the same but luckily your update preceded mine (it was better) and I ended up adding a reference only.

I agree on your proposed content for the rest of the page. I would suggest some simple operation just to wet the appetite and give some basic concept. Workbenches by the way would be a side-learning if we provide some examples movinv from one wb to another. I say I like the concept and don't find it unnatural. What I found confusing at the beginning was to find the same icons in different workbenches, sometimes with the same meaning and sometimes not ( Normand made a good example).

I also propose to keep the list of all command-icons somewhere as a quick reference (so instead of tags you have links to the page, that you follow only if you need), plus maybe the shortkeys; in the end, a cheatsheet. Maybe it'salrwady somewhere, but I couldn't find any.

Enrico

[ediloren]

Ok now I would like to go back to the basics, i.e. good pages, structure and style.

I think it was already agreed also in other posts that, to have a consistent documentation, we need rules.

I know everybody is scared of rules, either on imposing them (who am I to dictate rules for the others) or to follow them (how boring.. read them, learn them, abide to).

However, also I saw many posts of puzzled contributors asking some guidance on how to do this or that. Rules help in this respect, i.e. you have some hint on how to provide your content without breaking up what has already been done.
The other major benefit is to have a common look&feel and a common structure, leading eventually to a good documentation.

So I went on collecting all the information I could about either what has already been agreed or the best practices followed in the already existing body of documentation, and used the page WikiPages to provide the famous rules.

However, I am myself scared of imposing them, not wanting to bluntly step on the feet of so many people contributing to this valid project - I would like to have a full review by all of you before, if it is the case in the end, linking officially this page to the Help FreeCAD page. Remember anyway that rules are good for the 95% of the cases, but this does not mean that you cannot break them; but you must have a good reason to do so.

Please mind that in WikiPages I am giving rules mainly for style and structure, not for content. Good content is another topic, but I think that most of the content is already good, and must be organized accordingly. Content anyway can be the topic of another post (i.e. as Normand was pointing out, how far you should go in describing a workbench usage / model / etc.), not to mix feedback here.

The main philosophy that stressed in WikiPages is using templates whenever possible to style the pages. This is in line with the Wiki approach, where people should be more focused in providing a content and less to the markup (so the learning curve is shorter). Decoupling style from content is of course the same idea behind CSS; but in this case standard editors don't (and should not) touch the CSS, nor should use html tags.
Using templates to style the pages (as already extensively done) makes also it easy to postpone the decision about the graphical aspect of key strokes, menus, etc. that can also depend, as we know, from personal taste. But once everything is template, of course you just change the template to update everything in one shot. This is not true instead if we start using simple bold (wiki ''') for keystrokes (as myself wrongly proposed here - but I was thinking about the final render, not how to get there).

I also made arbitrary reference to two pages that IMHO are very good (and would need minimum editing to be fully in line with the WikiPages recommendations.
I would also deprecate the Std ViewScreenShot page instead; not to blame anybody, but I think this is far (in style!) from the latest trend as per GuiCommand model (i.e. headers are very small, 'synopsis' is really worst than 'description', etc.)

Moreover, I added some recommendations that are again somehow arbitrary, e.g. in the size of the pictures; but I saw too many pages with pictures one after the other with completely different widths, as well as not fitting in most (smaller) monitors, let alone in a printed (pdf) documentation.

I left a second section with the original brainstorming (minus what I mainly already absorbed as rules in the first section). This could be left there, or better, since can confuse new want-to-be editors, moved either to the Talk: of the same page or to another page completely.

So in a nutshell: please review WikiPages and post your comments under this topic.

Thank you
Ciao
Enrico

[yorik]

Looks good!
With the larger wiki theme we use now, full-page images can be up to 1024px. This still prints out fine in pdf...

[ediloren]

I waited a bit for further comments, but I see none, apart the 1024px from Yorik (already incorporated, even if on my laptop 1366 x 768 screen resolution the pictures 1024 px are larger than the screen, considering the width of the sidebar).

So now I would go 'live' with the WikiPages, linking it to the Help_FreeCAD page, as rules for Wiki pages creation and update.

Late comments are still on time..

Ciao
Enrico