WikiPages

Overview
This page gives common guidelines on the best practices to be followed when writing or updating FreeCAD documentation.

It also has the goal to bring together the threads that are dispersed in the forum and try to make order, being a single point of reference for FreeCAD documentation discussion and brainstorming, to better organize the wiki.

Before Starting
Before starting editing FreeCAD wiki pages, be sure to be familiar with the Wiki editing basics.

General Guidelines
Ideally, you should try to avoid duplicating the same information in different places. While it is simple to copy & paste some text, it will eventually lead to misaligned information when a page is update and the other not. You should insert the information in one place only, and make reference to this single point.

A possible solution for the above problem is the use of templates and transclusions (see Templates and transcluding pages if you are not familiar with this concept), but their usage for this goal is strongly discouraged. The reason is that in the printed manual created from the Wiki help you will have the same information printed over and over again; but even a reader using the Wiki can be confused by finding the same text in different pages. In case you need the same explanations in more than one point of the documentation, please consider creating a new page topic, and make explicit references (links) to this page.

Templates are heavily used, instead, for styling the text. For instance, there is a template for styling menu commands, like, another template to style keys to be pressed, like , etc.. This allows to have a consistent look and feel of the documentation, as well as to be able to update the style by simply changing the template. Please get familiar with the templates used in FreeCAD Wiki Help documentation before writing help pages.

Examples
Working by examples will help you keep the right track, and be ahead on the learning curve. So even if reading the following sections is highly recommended, you can quickly get familiar with the structure and style of FreeCAD wiki looking at the following pages, that can be considered reference for best style practices of FreeCAD documentation.

If you are consistent with this look & feel, you won't be far from a correct FreeCAD documentation page, and your contribution will blend more easily in the wiki.

Std_ViewScreenShot

General
You should normally not use a =header= for a page, since the page title is automatically added.

Remember that there is an index, so the docnav is not useful.

Links
You should use the original link name for the links whenever possible. This clarifies the referenced chapter in printed / pdf documentation. You must anyway avoid the usage of non-meaningful words for the link.

Bad link
For more information on this topic, click here.

So-so link
For more information on this topic, refer to drafting 2D objects.

Good link
For more information on this topic, see how to draft 2D objects in the Draft Workbench.

Command pages
The command pages should not be too long, they should only explain what a command can do and what it can't, and how to use it. You should keep pictures to a minimum, and not give too many examples - tutorials is where we should go in step-by-step details.

Restrictions should be documented right in the command page itself rather than elsewhere, possibly under a "restrictions" chapter.

Please refer to the Gui Command page for specific indications on Gui Command rules (naming, documenting, etc.).

Tutorials
Good tutorial examples are available at FreeCAD tutorial - Unofficial tutorial blog. Though they are not styled as FreeCAD wiki pages, they are a valid example of how a written tutorial should look like.

Expressions
You should avoid colloquial generic expressions as 'a couple'. Please re-phrase as 'some' if inteterminate, or with the correct cardinality.

Conciseness
Try to avoid repetitions to keep descriptions short.

Bad description
Part Design Workbench: the Part Design Workbench is a workbench for part design that aims to provide tools for modelling complex solid parts.

Good description
Part Design Workbench: aims to provide tools for modelling complex solid parts.

Templates
Basic Templates used in FreeCAD wiki pages (versions disordered, see Wiki_Template_List) follows.

General use of tags (e.g. TOC, KEY, TASK, VIEW Macros, tags, navigation bar, GuiCommand box, thumbnails, illustrations, screenshot, Image Sizes, ecc..) should be kept to a minimum, as they are distracting. The navigation bar is not very useful, since the toolbar is just a click away, in the workbench page which is linked in the GuiCommand box, which also includes a "See also" field.)

To have a global view on the chromatic aspect, see Basic Graphic Template.

Code
Code description should follow the text box, so that the description is structured according to the content. Accentuation should be used only on the word or lines that must strictly be accentuated.

Example of bad code description
makeAngularDimension (center,[angle1,angle2],p3): creates an angular Dimension from the given center, with the given list of angles, passing through p3. Returns the newly created object.

Example of good code description
makeAngularDimension (center,[angle1,angle2],p3)


 * Creates an angular Dimension from the given center, with the given list of angles, passing through p3.
 * Returns the newly created object.

General
Avoid thumbnails whenever possible. Pictures should be shown in their original size, to avoid the need for the user to continuously navigate back and forth between different pages. Most important even, in the automatically generated printed manual (e.g. pdf version), thumbnails may not be readable. Thumbnails should be used only as last resource.

Pictures must be uploaded through the Special:Upload page.

Screen capture
Recommended size for screen captures, to avoid any resizing when showing the picture, should be:
 * native 600x400 (or width=600 and height<=400), for Gui Command pages, to allow the picture to fit in the left part of the page, and for other standard snapshots
 * native 800x600 (or width=800 and height<=400), only for full screen images
 * Smaller sizes are possible when showing details, however use native resolution, not resizing or thumbnails, unless you have a very good reason to do so.
 * Avoid larger resolutions, as they won't be much portable to any kind of display.

If possible, you shouldn't depend too much on any OS. While of course achieving 100% independency from the underlying OS is not possible, you should use visual defaults whenever possible.

To ease documentation translations, if you put a screenshot showing the interface, you should not show the 3D model view in the same screenshot. In this way, the translator will not have to hunt for the model used to create the screenshot, and can simply take a screenshot of the localized interface. If there are drop down menus in the taskbar, the options should be listed in the text content.

Icons and graphics
Refer to this page for ready-to-use Artwork and Icon creation rules.

Models
The following pages contain models for FreeCAD documentation.

GuiCommand_model Boiler_NonCommand Wiki_Template_List Wiki_Resources Template:UnfinishedDocu

Translations
As per general consensus, the reference page is the English page, that should be created first. Moreover, if you want to change or add content in a page, you should do it in the the English page first, and only once the update is completed, port the modification to the translated page.

The FreeCAD wiki supports a Translation plugin which allows to manage translations between pages.

For an example of how it works once the translation module is activated on a page, please go to the Main Page. You will see a language menu bar at the bottom. It is automatically generated. Clicking on the German link you will get to Main_Page/de.

Right under the title, you can read "This page is a translated version of a page Main Page and the translation is 100% complete." Click on the "translated version" link to start translation. You can now change the translated strings.

You will notice that you cannot directly edit a page anymore once it's been marked as a translation. You have to go through the translation utility.

For further details on translation, see FreeCAD Wiki Translation Process under Localisation.

Other useful resources are:
 * Language Codes: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
 * Country Flags: http://en.wikipedia.org/wiki/Gallery_of_sovereign_state_flags
 * Google Translate: http://translate.google.com/

Workflow, Roadmap
Organize pages in the wiki

Content and Appearance:

 * Renato: width of the page, now much space is unused (only for monitor 16:10)
 * Renato: white background, text more readable
 * Renato:  links to similar commands, similar tools, scripts, examples, discussions, insights, forum, other... On all pages or only on some pages?

Templates
I think the things like this are also templates? This template contains headlines, icons, short textual description, long textual description, list elements. May be easier to handle when splitted in pieces (at least: icon list, description list, "full featured": array of someWorkbenchTools[icon|description,{2-4}]...) ?


 * Basic Template that would be useful

* PartDesignTools * _______________
 * Other Template

Forum
Some useful examples taken from the forum
 * Reflect on requests for help made ​​in the forum and use the given examples (if it is required an aid often means that the manual is not exhaustive, in the forum there are good examples, but hard to find)
 * Renato: Insert a link on the document page or insert the example or insert nothing?
 * Ralf: insert link(s) always in a field/area which is always there on every page. If there is nothing to link, there should be a text in this area as "There is currently no link to forum examples."
 * Ralf #2 examples: no examples at pages which are describing more than exactly the use of (probably mostly) a tool. If there would be examples (at different pages) which differ in various ways and are not comparable are confusing.
 * Ralf #3 examples: But beside of existing examples: defining a "standard model" (or some of them if needed for fairly different tasks as p.e. Part-Design vs. Arch) for really every example would promise a lot of advantages. The first one: if one like to try an example the related model file is available right there with the next click. Whatever the "standard model" could be - the most important condition it have to be usable for all examples/task from to simplest up to the most complex (FEM,assembly?!)
 * May be such an standard model and his incarnations could be also a kind of a "figurehead" for FC.
 * Ediloren (talk) 18:01, 3 September 2013 (CEST) : looks like a good idea but not too practical; I expect that the burden of adding examples for everything would be very high. I would prefer to resort on tutorials, videos, and forum unless somebody has really the time and commitment to follow this part (me not, sorry :) )

Documentation structure:

 * Links between pages (tree and hierarchy linear, orderly, full)
 * Renato: If there is an index the docnav does not serves.
 * Page titles descriptive
 * Renato: Translated or not translated? With the new translator seems outdated
 * Structure of the documentation (depending on the type of user and the type of documentation). Group some things? - If possible in any way: group everything to maximal seven (7) entrys (per group)(Ralf).:
 * Reference (needs indicate precise criteria) (Ralf: for me for advanced users/using, #3)
 * How to (Ralf: additional, #4)
 * Tutorial (Ralf: additional, #5)
 * External links
 * Themed (Ralf: 1st thing / start point while using the documentation? - for me #1)
 * examples - in relevant cases - the most basic example for using the tool / workbench /feature (is that possible with complex tools?) ; may be one "standard" example case for the most examples, if possible (so the fcstd file can be supplied and re-used for a lot of uses) for me #2 or to #1
 * linear (all, as now)
 * structured with sub-structures (very clear if there are no more than 5..7 entrys per structure layer)
 * task - specific (features is other than transform than handle mouse etc.)
 * FAQ
 * Books
 * Plugins
 * Macro

Documentation schemes
See Documentation schemes

Repository

 * fcstd file
 * pics, images
 * icons (there are almost all)
 * "Show your FreeCAD projects here!" archives

Who are the users:

 * New users FreeCAD:
 * Users without CAD experience -> not the job of the FreeCAD doc to teach them CAD - the job to teach them how to use FreeCAD? Renato: I think that FreeCAD is currently the only free CAD program with a professional approach. Many people exactly look for this to begin.
 * Users with CAD experience (2D/3D/parametric); users with 3D experience - no CAD
 * Users who know how to program (version?)


 * Users who know FreeCAD:
 * Users
 * Advanced users
 * Developers

What the users needs:

 * According to the category of the previous point they need different things (to be determined).
 * Renato: In my opinion the beginners to FreeCAD (or to CAD?) needs:
 * find the information immediately + Ralf: in the expected, consistent way
 * know what are the workbenches, when and how to use them, + Ralf: is this one workbench all I need or do I need more than one?
 * the commands that are available, + Ralf: in the workbench - for the task - all
 * the workflow to use, - Ralf: workflow sounds specific - may be the most basic way to use this - may be especially for tools there could be more than page per tool (as above: basic for beginners, extended use for advanced users)

Translations
''- The wiki, is the best way to create documentation FreeCAD? Would not it be better to reserve it for some issues and create a comprehensive manual for each version?'' ''- About updates, this is a crucial point, I've seen that you do not like docboock, and I do not intend to return to this theme, but docboock allows translators to easily work on documents. Allows you to download the entire document and compare it with the previous one. With this way changes are made always and only in the original document. Then the translators periodically (even daily if they want) downloading the document and compares with an earlier version and update it indicating the upgrade version. I've experienced that this procedure is very good. Can I do a similar thing with the wiki? In this way there is no need to continuously monitor Recent Changes and updates are easier to control.''
 * Consistent (the reference page is the English page, see the various discussions regarding the rules in the forum)
 * Updated (how?) + Ralf: 1st: Version, 2nd: frozen state of doc page - "this is the actual version of the documentation of ... for FC version xxx"; 3rd linked archiv pages of other versions (and maybe other frozen states), all with corresponding "tags" / marks
 * Use a document type that including at least one complete section of the manual (not just one page at a time). Comparable off line with an previous version. With "Recent changes" is difficult to follow all the changes, when they are frequent.
 * FCSTD files for Documentation (wandererfan wrote: It would be nice to have a repository for the fcstd files +Ralf and it would be very helpful - used to generate screenshots, etc. Then the 2nd author/translator could just open the fcstd with a different locale to generate the new screenshot. This would also for standardization of background colours, font sizes, etc. )
 * Renato. My personal:

Some notes taken from the forum
yorikvanhavre wrote: Actually we could do a little brainstorming, see things that should be changed on the wiki... I already thought of a couple of things: - a new wiki homepage with a clear view of the contents - better formatting of the 3 principal sections, for user (basically the command pages), for power users (everything about python) and the higher-level stuff (compiling, etc) - more professional aspect of the wiki pages - build a better and more strict model for command pages - find a good system to handle translations

gdo wrote: But maybe a survey to freecad users could help to understand precisely what is the beginners needs.

Ralf wrote: Even for the ones who are trying FreeCAD the first times, it's essential to find a consistent documentation otherwise they weren't motivated to give even some first tries.

And many more ... dispersed and mixed in: http://sourceforge.net/apps/phpbb/free-cad/viewtopic.php?f=8&t=3167 http://sourceforge.net/apps/phpbb/free-cad/viewtopic.php?f=10&t=3899 http://sourceforge.net/apps/phpbb/free-cad/viewtopic.php?f=8&t=3988 http://sourceforge.net/apps/phpbb/free-cad/viewtopic.php?f=12&t=3959 http://sourceforge.net/apps/phpbb/free-cad/viewtopic.php?f=13&t=4025

Examples of CAD documentation
http://help.solidworks.com/2013/English/SolidWorks/sldworks/c_Sketch_Fillets.htm?id=cb1f4dfbe23245aeb58d17af808ee10c#Pg0

Ralf: good: you can see where you are ; bad: a huge lot of entrys in the navigation / summary at left - the opposite of structured; sorry: pieces of the forum at the documentation page: what is the documentation page good for than? (but the link to the forum / forum search - ok.) http://www.gcad3d.org/ Ralf: thumbs up. clear, well structured. sometimes long but I don't know how to avoid that at some themes. Maybe the tree structure layers could be separated in two directions at the page for more place for the content. They have "last updates" I prefer "this version of the documentation is xxx and depend the program version xxy"

Reported by wandererfan guidelines for wiki authors: http://wiki.blender.org/index.php/Meta:Guides/Writer_Guide http://wiki.blender.org/index.php/Meta:Guides/Style_Guide Manual TOC: http://docs.gimp.org/2.8/en/ http://wiki.blender.org/index.php/Doc:2.6/Manual

Reported by Ralf: http://opensourceecology.org/wiki/FreeCAD

For the Italian translation also: http://tp.linux.it/

Next actions

 * 1) gather ideas
 * 2) build Table of Contents
 * 3) build good models (in the template created by Wandererfan)
 * 4) edit the master page in English (updated until a new FreeCAD version is released then freeze the document in pdf or doc or other)
 * 5) translate (updated until a new FreeCAD version is released then freeze)
 * 6) continue to develop the documentation for the new version of FreeCAD (repeats 4)
 * 7) continue to develop the translation for the new version of FreeCAD (repeats 5)

Other languages

 * Italiano