• HowToWriteArticles

Contributing to ArchicadWiki

First of all, thanks for contributing for ArchicadWiki! Before you do so, please read and understand a few guidelines that make ArchicadWiki easier to use:

• Log in before you begin writing. If you have not registered yet, do so, and please make sure your username reflects your real name and is in CamelWord format. Example: GregKmethy (2 capital letters, no space)

• Before you create a new article, do a search for keywords to find existing pages on the topic. If at all possible, do not create a new page, instead, expand an existing one. We currently have over a 1000 pages, and our goal should be DECREASING that number. Examples for decreasing the number of pages:

  • if you were to write about a bug with the DWG export, instead of creating a new article, collect other DWG bugs and put them all on one page called archicadwiki.com/DWG/KnownIssues.
  • if you were to write a tech note on a problem with the Nudge tool, but there are no current pages on the Nudge tool at all, then create the page archicadwiki.com/NudgeTool first. Hopefully, other users will find and expand the same article later.

About Page Titles

Writing a good page title is essential to make the information easily accessible.

• The title should be searchable - include all the keywords you would use to find that article. Still, keep it short - leave out filler words like "the" "and" "if", etc. Example: instead of "MagicMouseDoesNotWorkOnBlackComputers", use "MagicMouseProblem". (Better yet - just put it in the existing MagicMouse article).

• Use CamelWord format. As you have probably already figured out, this wiki engine automatically turns CamelWords into links. Avoid spaces in titles.

• Organize articles in Domains. E.g. all the Teamwork articles are in the archicadwiki.com/Teamwork/ domain and all the EcoDesigner articles are under the archicadwiki.com/EcoDesigner/ domain. Similar domains could be created, based on e.g. Archicad tool or feature names. Domains can be multi-level, so e.g. a domain called Teamwork/Troubleshooting/ makes sense.

• Bug or problem descriptions go under a special domain: Bugs. This makes it easy to make bug lists. Bug lists are based on searching for "Bugs/" in the title, so you can include that under another domain name. e.g. DWG/Bugs/Blablabla is a better domain name, since it will make it easier to navigate back to the DWG main page

Using templates

Now you are ready to write an article. Just type the title you have carefully dreamed up in the URL bar, and hit enter. Archicadwiki will tell you that the page does not exist and offer you to create a new empty page or choose a page template. Always choose a page template Here are the ones we use:

• ArticleTemplate is the most commonly used general-purpose Template. You will use this most of the times.

• BugTemplate is specialized for bug descriptions. It has the "Issue-Cause-Solution" formatting.

• TechSupGroupTemplate will create a page that is only visible for the TechSupGroup. This are pages for the group's internal knowledge base.

Keep the structure that the template offers. E.g. if you write about a bug, clearly describe the phenomenon, the cause, and the workaround.

Table of Contents

<<TableOfContents(2)>> Macro will create a TOC 2 levels deep. You can make it 3 levels deep by changing the parameter of the macro to 3. If article is short, delete or comment out this macro.

Header Box

Every page has a header box that contains general information about the content. Various page lists are aggregated based on this set of data, so set these values appropriately. (e.g. search is based on finding "• Archicad 14" in the page. That dot is important too!) Delete the unnecessary values (by default all possible values are listed).

Category

Categories work like tags. Think of good tags that describe the article well, then add them with the Category prefix in CamelWord format. E.g. CategoryMac CategoryEditing CategoryCrash CategoryHardware. Existing categories are listed on the CategoryCategory page, but don't worry if you have added a Category that does not exist yet. We will create it.

Tags/Categories are very important to include your article in automatic searches that use tags.

Related Pages

At the end of the page, there is a related pages section. This is an automatically generated list. You have to customize the FullSearch macro's parameters to make this work. This is how it works:

• <<FullSearch(keyword)>> will search for the "keyword" in all of the page's body text. This is usually slow, avoid this.

• <<FullSearch(t:keyword)>> will search for the "keyword" in the page titles. This should be used mostly

• <<FullSearch("key word")>> will search for the exact string "key word" This is great if there is a space in the string you want to search for

• <<FullSearch(t:keyword -t:excludeword)>> will list pages whose title include the keyword but does not include the "excludeword"

Trackback

Trackback will automatically list all the pages that has a link to this page (This is not a real trackback - it only lists pages from archicadwiki, but not external sources). You don't have to do anything to this, unless you have renamed an article. If you rename an article, don't forget to change the name in the Trackback as well. It uses the FullSearch macro described above.

Embedding your article in Archicadwiki

Your article only benefits others if they find it. To make sure your article is easy to find:

• Get the title of the article right
• Try to put it in the correct domain
• Make sure the header box is in place and includes correct information
• Add descriptive Categories (Tags)

• Find related articles, and reference your article in them. (e.g. from the Troubleshooting page)

• Announce your article on the FrontPage

• Consider announcing your article on Archicad-Talk

• Tell the marketing department so they can advertise it on Facebook and Twitter

Formatting

We recommend to use text-based editing of articles, which requires some knowledge of wiki-formatting. Archicadwiki also ha a GUI editor, but that does not work with all browsers. In theory it is posible to copy + paste documents from Word processing applications (such as Microsoft Word or OpenOffice.org,) preserving text formatting using the GUI Editor, but this will fail in many cases, because the WYSIWYG editor of this Wiki cannot always handle invalid markup code generated by these applications.

The complete list of formatting options is available here: HelpOnMoinWikiSyntax, but we do not use all that. To keep a consistent appearance of ArchicadWiki articles, please use the below formatting options - do use these, but do not use anything else, please. Definitely do not use colored fonts or colored backgrounds, and do not use HTML codes to change font size and type. That totally ruins the look of the page. Let CSS do the job - by modifying the CSS, we will be able to consistently update the look of Archicadwiki in the future.

Headings

We only use 3 levels of heading. Note: make sure there is no space after ending equal sign

Indentation

To indent paragraph:

• Start line with a space to indent paragraph with one level,
  • two spaces for two levels, etc.

Lists

 * Space-star-space
  * double-space-star-space
   * triple-space-star-space

• Space-star-space
  • double-space-star-space
    • triple-space-star-space

 1. space-number-fullstop-space
  1. double-space-number-fullstop-space
  1. double-space-number-fullstop-space
 1. space-number-fullstop-space 

1. space-number-fullstop-space
   1. double-space-number-fullstop-space
   2. double-space-number-fullstop-space
2. space-number-fullstop-space

 1.#6 List starting with number 6
 1. Blablabla

6. List starting with number 6
7. Blablabla

Tables

||'''A'''||'''B'''||'''C'''||
||1      ||2      ||3      ||

||<|2> cell spanning 2 rows ||cell in the 2nd column ||
||cell in the 2nd column of the 2nd row ||
||<-2> cell spanning 2 columns ||

Horizntal Rule

---- four dashes will create a horizontal line. Don't use too many of these

Text Decoration

There are more thane these, but please use only these.

Links

• Note: You can avoid a CamelWord to automatically turn into a link:

  CamelWord	CamelWord
  !CamelWord	CamelWord

Anchors

Attachments

Note: easiest way to upload an image is first including the link in the text, then saving the page - a paper clip icon will appear which you can click to upload image

Direct download: Download Graphisoft.PNG You can achieve this if you go to the "Attachments" page of the article, and copy the link from the "Get" button and format it as a link:

[[http://archicadwiki.com/HowToWriteArticles?action=AttachFile&do=get&target=Graphisoft.PNG|Download Graphisoft.PNG]]

Macros

The <<FullSearch>> and the <<TableOfContents(2)>> macros are discussed above, and they are included in the templates. The full list of macros are listed on HelpOnMacros. Do not put too many macros in a page - they slow down the loading of the page.