WikiPages

This page is an extension of the Help:Editing page and gives common guidelines for writing and updating the FreeCAD wiki documentation. It summarizes several discussions and brainstorming sessions.

Before starting

 * This wiki documentation is based on MediaWiki, the same software that powers Wikipedia. If you have contributed to Wikipedia, editing FreeCAD wiki pages should be easy.
 * Contrary to Wikipedia, the FreeCAD wiki is write-protected to avoid spam. You must request an account on the forum.
 * If you have never used wiki software before, please read Help:Editing to become familiar with the markup that is used.
 * For advanced use of the wiki software, see MediaWiki Help:Contents. Not all features of MediaWiki are available in this FreeCAD wiki, but many are.
 * We like to keep the documentation easy to read, so avoid using complex features. Keep it simple.
 * Use a sandbox to test your code, for example, FreeCADDocu:Sandbox or a particular page with your name Sandbox:Yourname.
 * Please be aware of the translations. The FreeCAD wiki uses automated translation support to provide pages in many languages. For every page multiple language versions can exist. On many pages you will see tags like  and many single tags like  . The latter are created by the translation system. They link the headers and paragraphs to their translated versions. You should not change them as that would destroy those links. It is however fine to move paragraphs or change wording as long as the tags stay with them. If you remove a header or a paragraph you should also remove the tag belonging to it. Please be aware that changes to existing headers and paragraphs affect the current translations. Your changes should be worth it. Do not worry when adding new material because the system will add new tags automatically after your edits. For more information see Localisation and the original Mediawiki:Extension:Translate page.

Concise descriptions
When describing FreeCAD try to be concise and to the point. Describe what FreeCAD does, not what FreeCAD does not do. Try to keep descriptions short and avoid repetition. Also avoid colloquial expressions such as 'a couple'. Use 'some' when dealing with an indeterminate number, or specify the correct quantity.


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


 * Good description
 * PartDesign Workbench: aims to provide tools for modelling complex solid parts.

Centralized information
Avoid duplicating the same information in different places. Insert the information in a new page, and link to this page from other pages that require this information.

Do not use transclusion of pages (Help:Editing#Templates and transcluding pages), as this makes the wiki difficult to translate. Use only the templates described below in #Templates.

Styling
Templates are used to style the help pages. They give the documentation a consistent look and feel. There is a template for menu commands,, a template to style keys to be pressed, , to show a Boolean value, , etc. Please get familiar with the #Templates section before writing help pages.

Temporary flags
If you are working on a large page it is advisable to mark the page either as a work in progress or as unfinished. This assures that wiki admins don't mark your page as ready for translation while you are still changing it.

To flag a page add either  or   as the first line. With  you invite others to join you in finishing the page, while   indicates that you will do the work yourself and others should give you some time.

Once the work is done, please don't forget to remove the flags!

Examples
To quickly get familiar with the structure and style of the FreeCAD wiki look at the model page: GuiCommand model.

Structure
The User hub provides a Table of Contents. This is used as the main reference for automatically building the offline help you can reach from FreeCAD, as well as the offline PDF documentation.

The Template:Docnav is used to sequentially link pages, following to the structure of the Table of Contents. See #Templates for a list of all templates.

Page names
Page names should be short, and they should use sentence case: all words except the first one and proper names, should be in lowercase. This is the style used by Wikipedia for their articles.


 * Bad page name:
 * Tutorial On The Construction Of AeroCompany Airplanes


 * Good page name:
 * Tutorial on the construction of AeroCompany airplanes

The names of top level workbench pages must have this format:, where   is the name of the workbench, for example PartDesign Workbench. And the names of pages describing the commands (or tools) belonging to a workbench must have this format:, for example PartDesign Pad. Note that you should use the command name as it occurs in the source code.

A previous convention was to use title case: every word should begin with a capital letter, unless they are articles, prepositions, conjunctions, or other grammatical particles (f.e. 'of', 'on', 'in', 'a', 'an', 'and'). There are many existing pages using this style, but it is discouraged for new pages. This was discussed in the forum thread (Lowercase links) Use a lower case title for a wiki page.

Headers
Like page names, headers should be short and use sentence case. You should not use  headers  in your wiki markup since the page title is automatically added as the.

Links
You should use the original link name for links whenever possible. This clarifies the referenced page in printed or offline documentation. Please avoid non-meaningful words for the link.


 * Bad link
 * For more information on drafting 2D objects click here.


 * Good link
 * For more information on drafting 2D objects refer to the Draft Workbench.

The preferred format for a link is:

To translate this line:

Note that for the part before the  character, the actual link, case is relevant. If your page name is  the link will fail if you type   (upper case P). Before the  character all spaces should be replaced by underscores. This is to assist translators using translation software, without the underscores the link would be translated by the software which is undesirable.

To link to a certain paragraph add a  sign and its header to the page name. Example:

To translate this line:

Within the same page you can omit the page name. Example:

To link to the top of the page you can use:

This link will even work if there is no 'Top' paragraph on the page. It is especially useful for long pages as it allows the user to quickly jump back to the table of content. You can put it at the end of each paragraph. Make sure there is an empty line before and after the link.

Workbench pages
A top level workbench page should start with:
 * A description of what the workbench is used for.
 * An image to illustrate the description.

See #Screen capture for conventions on including images.

Command pages
Command pages describing workbench tools 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 and examples to a minimum. Tutorials can expand on how to use the tool and provide step-by-step details.

Please refer to the GuiCommand model page for more details.

Tutorials
A well written tutorial should teach how to achieve certain practical results quickly. It shouldn't be too long, but should include sufficient step-by-step instructions and images to guide the user. As FreeCAD evolves, tutorials may become obsolete, so it is important to mention the FreeCAD version used in, or required for, a tutorial.

See the tutorial guidelines for a basic idea on how to set up a tutorial.

For more examples visit the Tutorials page.

Templates
Styling of the FreeCAD wiki pages is achieved through the use of templates (Help:Editing). They ensure a standardized look and feel across all pages, and also make it possible to re-style the wiki. You can see the complete list of defined templates by accessing Special:PrefixIndex/Template:. But please only use the templates listed in the tables below. Only in very special cases should you use HTML tags directly.

Click on the template link to see the usage instructions for a template, and to see its implementation. Templates are a powerful feature of the MediaWiki software. You should be an experienced wiki user if you wish to propose additions and modifications to existing templates. If implemented incorrectly, templates make it difficult to translate pages into other languages, so their use should be limited to text formatting, page transclusion should be avoided. See MediaWiki Help:Templates to learn more.

Simple templates
These templates accept a simple text parameter, and format it with a particular style.

Complex templates
These templates require more input parameters, or produce a block of text with a particular format.

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

Code
Code must be styled using the Code template. The description of such code should follow afterwards. Accentuation should be strictly used only on the word or lines that must be accentuated.

Python code should adhere to the general recommendations established by PEP8: Style Guide for Python Code. In particular, parentheses should immediately follow the function name, and a space should follow a comma. This makes the code more readable.

Example of good code description

 * Creates an angular dimension from the given point, the  containing  and, and passing through point.
 * Returns the newly created object.

Graphics
Images and screenshots are necessary to produce a complete documentation of FreeCAD. Images are particularly useful to illustrate examples and tutorials.

General
Avoid thumbnails and resizing bitmap pictures (downsizing or upscaling). Pictures should be shown in their original size, so they present sufficient detail and are readable if they include text. The exception to this are SVG images, which can be scaled to any desired size without losing detail.

Avoid animated pictures (GIF) in the general Gui Command help pages. Animations and videos should be reserved for tutorials not intended to be used as offline PDF documentation.

Pictures must be uploaded through the Special:Upload page.

Name
Give a meaningful name to your image. If you have a picture that showcases the characteristics of a particular command, you should use the same name as the command with at the end.
 * For the command Draft Offset the image should be called Draft Offset example.jpg.
 * For the command Arch Space the image should be called Arch Space example.jpg.

Screen capture
Recommended sizes for screen captures are:
 * Native 400x200 (or width=400 and height<=200), for Gui Command pages, to allow the picture to fit in the left part of the page, and for other standard snapshots.
 * Native 600x400 (or width=600 and height<=400), for Gui Command pages, when you really need a bigger picture, and still allow the picture to fit in the left part of the page, and for other standard snapshots.
 * Native 1024x768 (or width=1024 and height<=768), 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 very portable to other kinds of display or in the printed PDF documentation.

You shouldn't depend on any particular configuration of your desktop or operating system when you show screenshots. You should use visual defaults of the FreeCAD interface whenever possible.

To create a screen capture you can use the default options provided by your OS or use one of these macros: Macro Snip and  Macro Screen Wiki.

Text
To ease documentation translations, take separate pictures of the interface and the 3D model viewport. The picture of the 3D model can be reused in every translation, while a translator can take a picture of the localized interface if necessary.

If your screen capture contains text use the same resolution of the original interface in FreeCAD so that text is readable.

Bad sizing for reading text


In the second picture the text is less clear and there are visual artifacts due to rescaling the original width from 307px to 190px.

Icons and graphics
Refer to the Artwork page for all artwork and icons that have been created for FreeCAD, which can be immediately reused in documentation pages. If you would like to contribute with icons, please read the Artwork Guidelines.

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

The FreeCAD wiki supports a translation extension that allows managing translations between pages easier; for details, see Localisation Translating the wiki.

Other useful resources are:
 * ISO language codes to identify the two-letter code for a particular language that you want to translate to.
 * Country flags to identify a country's flag for use in relevant localized pages.
 * Google Translate for help with translating languages.
 * Deepl translator for help with translating languages.

Setting GuiCommand
translated:

Setting template
translated:

Setting link
translated:

or:

translated:

Setting Docnav
To localize the Template:Docnav navigation bar, see this thread in the forum Docnav previous/next.

Essentially, a new translated template needs to be created, Template:Docnav/it.

The translated template should include the appropriate localized links as the 'previous' and 'next' parameters, together with the translated text:

The translated template should include the appropriate localized links as the 'previous' and 'next' parameters with icon, together with the translated text:

Also includes the appropriate language category

If the localized category is not included in the translated template, the translated template will remain in the default English category.

Using special pages

 * Special:LonelyPages lists those pages that are not linked from other pages in the FreeCAD wiki, therefore nobody can access these pages. If you find any in your native language, try to create the connection that exists in the English version of the page, otherwise no one can read them.
 * Special:UncategorizedPages lists pages without an assigned category, therefore they do not appear when you browse the wiki by categories. Assign a category.
 * Special:WantedPages lists pages that are called in a page, but that do not exist. These are shown as red links in the text. Deprecated and very annoying.
 * Others Wanted (files and templates)
 * Special:WantedCategories lists categories that are used in a page, but that do not exist. They can be created immediately by clicking on the red link. Skip.
 * Special:Categories lists all categories in the wiki. They allow you to compare the number of pages inside a translated category, which should preferably match then number of pages inside the English language category.
 * Special:ListRedirects lists all redirected pages. If there is any red links, something does not work well. Investigate which link is missing. Light blue links lead to pages outside the site, no problem.
 * Special:RecentChanges lists the most recent changes done to the wiki, including the pages changed, the number of changes to a particular page, whether these were additions or subtractions, and the user responsible.
 * Special:LanguageStats shows translation statistics for all message groups for a single language. Shows the parts not translated in a given language, only for those pages marked for translation. To see what has not been translated, set the language code and press Show statistics. It also contains the link to see what has been recently translated into that language. Note: if entering the English code en shows pages, it is likely that the original page contains markup errors, with the exception of the sidebar.
 * Special:PageTranslation lists all pages marked for translation, and those unmarked but that have translation tags. Only administrators can mark pages for translation.
 * Category:Pages to delete: lists all pages that should be deleted because they were created by mistake, are obsolete, or no longer necessary.

Rename pages
Since FreeCAD is a project under permanent development, it is necessary to revise the Wiki pages. One task is hereby to check if the file and page names are still following the conventions. If a workbench changed for example a component name, the Wiki page describing it must be renamed. Thi can only be done by Wiki administrators. To inform them, open a topic in the Wiki forum and list the necessary renaming in this form:

old name                    new name OLD_PAGE_NAME   NEW_PAGE_NAME ...

Move files
To rename files it is in many cases to move them. That means they will become a new file under a new name while its content remains.

To move a file, go to its page ( https://www.freecadweb.org/wiki/File:***.*** ) and click at the upper right on the menu More and select there the appearing menu Move. This opens a page with all info on how to perform a movement.

Delete files and pages
In case you need to delete a file, go to its page ( https://www.freecadweb.org/wiki/File:***.*** ) and edit it. No matter if the page is blank or not, add this command as first element to the page:   and describe below why this should be deleted. Additonally, open a topic in the Wiki forum.

For pages the procedure is the same.

Robots
Head to WikiRobots to find instructions on how to set up and use robots to automate repetitive tasks on the FreeCAD Wiki.

Discussion
The Development/Wiki subforum in the FreeCAD forum provides a dedicated space for discussing improvements on the wiki topics and appearance. Direct your questions and suggestions there.

English
See Glossary.

Other languages

 * Italiano
 * Français
 * Deutsch