WikiPages: Difference between revisions

From FreeCAD Documentation
mNo edit summary
(changed format list)
Line 173: Line 173:


===Basic Graphic Template===
===Basic Graphic Template===
-------
DASH
DASH
{{DASH|text}}
{{DASH|text}}
-------
Disambig
Disambig
<div class="notice metadata" id="disambig">
<div class="notice metadata" id="disambig">
Line 181: Line 183:
|style="vertical-align:middle;"|''This [[Wikipedia:Disambiguation|disambiguation]] page lists articles associated with the same title. If an [[Special:Whatlinkshere/{{NAMESPACE}}:{{PAGENAME}}|internal link]] led you here, you may wish to change the link to point directly to the intended article.''
|style="vertical-align:middle;"|''This [[Wikipedia:Disambiguation|disambiguation]] page lists articles associated with the same title. If an [[Special:Whatlinkshere/{{NAMESPACE}}:{{PAGENAME}}|internal link]] led you here, you may wish to change the link to point directly to the intended article.''
|}</div>
|}</div>
--------
Docnav
Docnav
<div class="docnav">
<div class="docnav">
Line 228: Line 231:
====Scheme 1 based on the type of '''users''' (for example, to modify)====
====Scheme 1 based on the type of '''users''' (for example, to modify)====


DOC
*DOC
# users
*# users
## overview FreeCAD
*## overview FreeCAD
### FreeCAD - Commons
*### FreeCAD - Commons
#### link to an introduction to CAD / 3D CAD / parametric 3D CAD - wikipedia or similar?
*####* page1 ? link to an introduction to CAD / 3D CAD / parametric 3D CAD - wikipedia or similar?
*####* page2 ? General function of FreeCAD (workbench principle) - small problem: if someone like "just to start" - the workbench priciple should aligned with the GUI, mouse model etc. All in overview or all in getting started? I prefer in "getting started"
#### page1
*####* page3
#### General function of FreeCAD (workbench principle) - small problem: if someone like "just to start" - the workbench priciple should aligned with the GUI, mouse model etc. All in overview or all in getting started? I prefer in "getting started"
#### page2
*### abc
*####* page1 ? short version / explanation of the license (see below)
### ab
*####* page2 may be possibilities and limits of FreeCAD: what is possible an what not - if this is possible to say "generic"
#### page1 ? short version / explanation of the license (see below)
*####* page3
#### page2 may be possibilities and limits of FreeCAD: what is possible an what not - if this is possible to say "generic"
## getting started
*## getting started
### Description of the GUI (yet difficult: at this point/moment this page don't need to be to exhaustive - but then a second "stage" of the same page would be needed - suggestions?)
*### Description of the GUI (yet difficult: at this point/moment this page don't need to be to exhaustive - but then a second "stage" of the same page would be needed - suggestions?)
### mouse model
*### mouse model
### keyboard shortcuts
*### keyboard shortcuts
### may be here: the principle how FreeCAD handles transformation (as properties) of objects and how handles FreeCAD the tree and the dependencies of features according to the tree (too much here: which leads to actual limitations while using some tools, patterns p.e.). Bad, when here: very generic, unusable for one who like to start with something concrete - is abstract - Good: it's the right place to to make the acquaintance of this principles, one time.
*### may be here: the principle how FreeCAD handles transformation (as properties) of objects and how handles FreeCAD the tree and the dependencies of features according to the tree (too much here: which leads to actual limitations while using some tools, patterns p.e.). Bad, when here: very generic, unusable for one who like to start with something concrete - is abstract - Good: it's the right place to to make the acquaintance of this principles, one time.
### 2D
*### Operate in 2D
#### drawing objects
*#### drawing objects
#### modifying objects
*####* tool a
#### utility tools
*####* tool b
#### ____
*####* tool c
*#### modifying objects
### 3D
#### primitives
*####* tool a
#### modifying objects
*####* tool b
#### _______
*####* tool c
#### ________
*#### utility tools
*####* tool a
# power users
*####* tool b
## Pivy
## script
*####* tool c
*#### ____
# developers
*### Operate in 3D
## compiling FreeCAD
*#### primitives
## modifying FreeCAD
*####*
# install - Ralf: for me personal that's a very important point: what are the conditions of use? (there is always a page with a shorted content of the license), ...
*####*
# license
*#### modifying objects
(Ralf: here at my box I have a problem with the wrap of long lines inside of the boxes and I believe, that's not new)
*####*
*####*
*#### _______
*#### ________
*# power users
*## Pivy
*## script
*# developers
*## compiling FreeCAD
*## modifying FreeCAD
*# install - Ralf: for me personal that's a very important point: what are the conditions of use? (there is always a page with a shorted content of the license), ...
*# license
(Ralf: here at my box I have a problem with the wrap of long lines inside of the boxes and I believe, that's not new) (Renato: changed)


====Scheme 2 based on the type of '''documents''' (for example, to modify)====
====Scheme 2 based on the type of '''documents''' (for example, to modify)====


DOC
* DOC
# reference
*# reference
## workbench a
*## workbench a
### command a
*### command a
#### intro
*####* intro
#### image
*####* image
#### how to use
*####* how to use
#### option
*####* option
#### see also
*####* see also
#### link
*####* link
#### script
*####* script
#### macro
*####* macro
#### dev info
*####* dev info
#### ____
*####* ____
### command b
*### command b
#### intro
*####* intro
#### image
*####* image
#### how to use
*####* how to use
#### option
*####* option
#### see also
*####* see also
#### link
*####* link
#### script
*####* script
#### macro
*####* macro
#### dev info
*####* dev info
*####* ____
## workbench b
### command a
*## workbench b
#### intro
*### command a
#### image
*####* intro
#### how to use
*####* image
#### option
*####* how to use
#### see also
*####* option
#### link
*####* see also
#### script
*####* link
#### macro
*####* script
#### dev info
*####* macro
### command b
*####* dev info
*####* ____
# user manual
*### command b
## navigation
*# user manual
## manipulators
*## navigation
## preferences
*## manipulators
## placement
*## preferences
## ______
*## placement
# "standard" defined FC-files (the example files)
*## ______
# tutorials
*# "standard" defined FC-files (the example files)
# books
*# tutorials
# FAQ
*# books
## install
## use
*# FAQ
*## install
## script & develop
*## use
## ''Show your FreeCAD projects here!'' archives
*## script & develop
*## ''Show your FreeCAD projects here!'' archives


( Ralf: a lot of my books put the reference at the end) ok
( Ralf: a lot of my books put the reference at the end) (Renato: ok)


====Scheme 3 '''mixed''' (for example, to modify)====
====Scheme 3 '''mixed''' (for example, to modify)====

Revision as of 19:47, 16 May 2013

Page in progress.

I hope someone will correct this text.

Contributions are welcome.

Organize pages in the wiki

This simple page, which at the moment is just a sketch, wants to bring together the threads that are dispersed in the forum and try to make order. I hope someone will add the contents that serve to better organize the wiki.

Workflow, Roadmap

Purpose and principles

...

Outcome

...

Brainstorming

On this page

Organizing

...

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)

Content and Appearance:

  • Content of pages (only useful things, depending on the type of user and type of document, without unnecessary duplication)
  • Appearance of the pages (pages clean, neat, easy to read, professional?)
    • Renato: width of the page, now much space is unused (only for monitor 16:10)
    • Renato: white background, text more readable


Style page

  • Code
    • Renato: Description in the text box or follows? Compare Draft_Dimension#Scripting and Draft_Dimension/it#Script
      • Ralf: "Script" is clear for me, "Scripting" not. Why use anything like that box that accent whatever when everything (or at least a lot of...) is accented? Moreover the "Script" version is structured according to the content, the "Scripting" not at all (in this part). General: use a accentuation for some word or lines that needs to be accentuated. General #2: if possible, we should use the same accentuation for same or atleast similar things, "layers" I would call this things. (May be Titles, Commands, so on).
  • Screen capture
    • Renato: From Windows or Linux system? And with which theme?
      • Ralf: if possible avoid to see which OS. We're Open Source, GNU and BSD licensed - we shouldn't depend to much at any OS.
      • Ralf: Theme - the one which is at this version "default" "out of the box" - of course (?)
  • See also
    • Renato: links to similar commands, similar tools, scripts, examples, discussions, insights, forum, other... On all pages or only on some pages?
  • Basic Template found (versions disordered, see Wiki_Template_List, some rarely used)
Template Note 1 Note 2
Clear ok
Click rarely used superimpose an invisible link on an image
DASH rarely used text box type code, colorful background
Disambig not used
Docnav ok
FALSE color or black and gray? FALSE FALSE FALSE False False False False false
GuiCommand ok the main anchor on documenting GuiCommands
Information not used
KEY Renato: Useful, but use it only once per type on a page
Languages ok obsolete with the new wiki
Macro ok, used
Message rarely used for message not very important
VeryImportantMessage ok
Prettytable used for this table
PropertyView background green or gray? VIEW Property View Property
Properties Title spelling. color or black and gray?
PropertyTasks color or black and gray? Renato: serve but too many disturbing reading
Screenshot
Softredirect
TasksTag color or black and gray?
TRUE color or black and gray?
UnfinishedDocu ok mark not finished documentation.
Version FreeCAD version, small text
  • Basic Template that would be useful
Template Note Note
suggestion

caution

useful? as Message?
alert useful? as VeryImportantMessage?
idea useful?
shortcut as KEY?

I think the things like this are also templates? {{PartDesign Tools}} 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 Graphic Template


DASH

text

Disambig


Docnav

[[{{{1}}}|< previous: {{{1}}}]]
[[{{{2}}}|next: {{{2}}} >]]


.......to be continued......

Other Template

  • PartDesignTools
  • _______________

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.


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?:
    • 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

Scheme 1 based on the type of users (for example, to modify)

  • DOC
    1. users
      1. overview FreeCAD
        1. FreeCAD - Commons
            • page1 ? link to an introduction to CAD / 3D CAD / parametric 3D CAD - wikipedia or similar?
            • page2 ? General function of FreeCAD (workbench principle) - small problem: if someone like "just to start" - the workbench priciple should aligned with the GUI, mouse model etc. All in overview or all in getting started? I prefer in "getting started"
            • page3
        2. abc
            • page1 ? short version / explanation of the license (see below)
            • page2 may be possibilities and limits of FreeCAD: what is possible an what not - if this is possible to say "generic"
            • page3
      2. getting started
        1. Description of the GUI (yet difficult: at this point/moment this page don't need to be to exhaustive - but then a second "stage" of the same page would be needed - suggestions?)
        2. mouse model
        3. keyboard shortcuts
        4. may be here: the principle how FreeCAD handles transformation (as properties) of objects and how handles FreeCAD the tree and the dependencies of features according to the tree (too much here: which leads to actual limitations while using some tools, patterns p.e.). Bad, when here: very generic, unusable for one who like to start with something concrete - is abstract - Good: it's the right place to to make the acquaintance of this principles, one time.
        5. Operate in 2D
          1. drawing objects
            • tool a
            • tool b
            • tool c
          2. modifying objects
            • tool a
            • tool b
            • tool c
          3. utility tools
            • tool a
            • tool b
            • tool c
          4. ____
        6. Operate in 3D
          1. primitives
          2. modifying objects
          3. _______
          4. ________
    2. power users
      1. Pivy
      2. script
    3. developers
      1. compiling FreeCAD
      2. modifying FreeCAD
    4. install - Ralf: for me personal that's a very important point: what are the conditions of use? (there is always a page with a shorted content of the license), ...
    5. license

(Ralf: here at my box I have a problem with the wrap of long lines inside of the boxes and I believe, that's not new) (Renato: changed)

Scheme 2 based on the type of documents (for example, to modify)

  • DOC
    1. reference
      1. workbench a
        1. command a
            • intro
            • image
            • how to use
            • option
            • see also
            • link
            • script
            • macro
            • dev info
            • ____
        2. command b
            • intro
            • image
            • how to use
            • option
            • see also
            • link
            • script
            • macro
            • dev info
            • ____
      2. workbench b
        1. command a
            • intro
            • image
            • how to use
            • option
            • see also
            • link
            • script
            • macro
            • dev info
            • ____
        2. command b
    2. user manual
      1. navigation
      2. manipulators
      3. preferences
      4. placement
      5. ______
    3. "standard" defined FC-files (the example files)
    4. tutorials
    5. books
    6. FAQ
      1. install
      2. use
      3. script & develop
      4. Show your FreeCAD projects here! archives

( Ralf: a lot of my books put the reference at the end) (Renato: ok)

Scheme 3 mixed (for example, to modify)

todo

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?
    • 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)
    • ....

Contributions

  • Rules to be respected - Previously defined in "Style page".
    • use of: TOC, KEY, TASK, VIEW Macros, tags, navigation bar, GuiCommand box, thumbnails, illustrations, screenshot, Image Sizes, ecc.. , (normandc wrote:... the tags are distracting and should not be used so much in the command reference pages....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.)
    • content of the texts.

Translations

  • 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:

- 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.

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

Links to FreeCAD pages

GuiCommand_model
Boiler_NonCommand
Wiki_Template_List
Wiki_Resources
Template:UnfinishedDocu

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/


Available translations of this page: {{|}} {{|}}