How To Contribute

Keep the discussion going

Sometimes (php online manual is the best example), the users contributed notes provide a greater help than the documentation itself. We are aiming to do the same here. There are two places where we encourage you to keep discussion.

• Dedicated MediaWiki page (discussion tab) where we AA users can ask question and get answers pretty much like on the ActionApps mailing lists.
• If you think your suggestion is directly related to a section or a paragraph in the documenatation and would be useful for a majority of people following that section (even in the printed version) in the documenetation, please add a user contributed note, as per example below:

--Marek 26 July 2005 12:50 (CEST)

To add a user contributed note, or add something to somebody else's note, simply add the text to the right place, and enclose it in:

<div id="usernotes"><div class="note"><strong>--~~~~</strong><div class="text">
... here goes your text, you can use html and wiki syntax as normal ...
</div></div></div>

--Marek 26 July 2005 12:56 (CEST)

You don't have to type the complicated <div... manually. There is a custom button in the MediaWiki, looking like this . Type in your text, highlight it, click on the button and there you go :-)

Go and edit it

Any page within the /documentation can be edited by anybody. So if you see that there is a typo, you would say things differently, you see some vandalism that can be fixed by rolling back, or you want to add comment, please do so. Yes, you have to be logged in, but you simply create yourself a new account. If you forget your password, create a new one. Just use something close to your real name, so that we know who you are.

Editorial guidelines

Writing

~ToDo: Write general guidelines for writers

--Marek 26 September 2005 18:45 (CEST)

If you are converting an existing text from HTML format to Wiki, David keeps a working installation of the HTML to Wiki perl module. Saves a lot of teadious work.

--Marek 22 July 2005 18:25 (CEST)

TIP: If you are using Firefox, you can install a free SpellChecker toolbar called SpellBound. It helps a lot. For Firefox > 1.5, follow this advice.

Creating and uploading images

• To create a new drawing, please use some vector format so that the image can be easily updated later if necessary. The default support for vector graphics in browsers is limited, so what we do is we publish upload the bitmap image, and somewhere alongside it the vector graphics as well. The following example uses .png for bitmap and SVG for a vector. The SVG/XML is included at the bottom of the image summary page.

• To add an image (converted drawing, screenshot, a picture of a happy ActionApps user), simply use the Embeded Image button, change the name of the file (make sure it has a correct extension), save the page, click on the link generated and upload the image following the provided simple file upload form. If you need more help, read the comprehensive Help:Images and other uploaded files.

--Marek 27 July 2005 15:31 (CEST)

There is a great open source editor for vector graphics which I use for all the images. It's called Inkscape and it's fun to work with.

--Marek 10 October 2005 19:19 (CEST)

For adding video sequences that quide people through the UI, you can use a software called Wink

ToDos

If you for whatever reason can't finish certain sectios, put in this:

~ToDo: <What needs to be done>

Don't forget the leading space. It's easy for anybody to search for all ~ToDo, and even in the compact list of search results it's clear what else needs to be written, so you can pick your favourite topic straigt away and a have a good time writing about it :-) .

Hooks for ActionApps interface

If you are writing about something that you think should be linked from the ActionApps interface, mark it with

~Hook: Breadcrumbs -> in the -> AA navigation

Again, don't forget the leading space.

Terms

We are trying to keep a list of comonnly used terms (mainly aa specific). Please get yourself familiar with what is there and

• Keep linking to it as you write
• Add new terms if you feel something significantly important is missing

To link to a term inside the text simply do (Field as and example term):

[[Term#Field |Field]]

Related articles

By moving the documentation from AA to wiki we have lost an easy way to add related documents (the "See also:" ones). Please try to keep doing them manually.

New chapters

~ToDo: Write guidelines for creating new chapters.    

Syntax help, tips and recommendations

Wiki syntax help, Help:Images and other uploaded files. Guide for Editors

Contributing to the Demo Site

We use live examples, indicated in the text by icon. There is a AA demo install (demo.actionapps.org), which is being refreshed every night with the content of the main install (/apc-aa) database, except for the permissions (tables user and perms). The purpose of this model is so that people can go in as admins and play around with stuff, but the garbage and all the damage done to it is removed overnight and the fresh new demo is born again. So, if you need to create an example, do it in the master install, and it will be copied over. If you need access to the main install, contact me (marek at ecn dot cz) developers. Also, make sure you add an entry about the demo to the List of Live Demos page.

I tend to create a special account for each excercise, so that the user works only with the slice or two that is being used in the example and is not bothered by the (unrelated) rest. I add the username and password to the url pointing to the demo, i.e. :

demo....pps.org/aa/admin/se_views.php3?slice_id=48696572617263686963616c20436174&u=demo01&p=demo01

Note: This login form patch had to be applied to make it work on the demo site.

Translating this documentation into other languages

At the moment we have one MediaWiki install for English and one MediaWiki installation for Spanish. We propose to use MediaWiki Interlanguage Linkingto interlink those two. It works like this:

When there is a page in spanish (let's say "Portada") that should be linked to a corresponding english page (say "Main Page") and vice versa, the editor should put a wiki link like this:

[[en:Main Page]] towards the bottom of the spanish page, and [[en:Portada]] towards the bottom of the english page

The link won't display, instead it will trigger a box on the left column saying Other languages/Otros Idiomas listing all the languages that are available for that page. Visit Main Page to see it in action.