Help:Guidelines for editing Discussions

Introduction

This page will show you how to create or edit a Discussion summary on this wiki.

E-Discussions are originally run on the KM4Dev mailing list. Members are then encouraged to summarize and categorize Discussions using this wiki, in order to consolidate the shared knowledge and make it easy to find and re-use.

Creating a new Discussion

To add an Discussion, go to the dedicated form and choose a title for the Discussion.

Notes:

• Do not include slashes "/" in the title
• In choosing a title, try to make it short and synthetic of the content of the Discussion. Always consider that you should be able to understand what each Discussion is about by just reading its title.
• A link to the form for creating Discussions is also available in the left side bar of this wiki, in the "Add content" section.

Error creating thumbnail: File missing

Editing an existing Discussion

To edit an E-Discussion, go to the Discussion and click on the "Edit with form" tab on top.

Error creating thumbnail: File missing

Using the form: step by step instructions

Once you start editing a new or existing Discussion, you will see a form designed to guide you through the preparation of the page.

The form features multiple sections which show up collapsed by default. To edit a section, uncollapse it using the arrow on the right.

Error creating thumbnail: File missing

Section 1: Topic Areas

Topic Areas are thematic categories that you can assign to Discussions, in order to make them easy to find using thematic criteria.

There are two kinds of topics you can assign to Discussions:

• Hard Categories
• Custom Keywords

Hard categories are predefined values chosen by the community. Custom keywords are custom values you can type into the dedicated field.

Error creating thumbnail: File missing

Notes:

• You can assign multiple values both in the Hard Categories and in the Custom Keywords fields.
• The Custom Keywords field autocompletes as you type, based on values already used for that field, in other Discussions. This is to minimize the risk of creating duplicates (es: "Knowledge Sharing" and "KS"). A good practice is to take a look at the complete list of existing keywords before typing new values into this field.

Section 2: Regions and Countries

Some Discussions are related to specific regions/countries. This section in the form allows you to select regions and countries of relevance.

If the Discussion is not related to any specific country or region, simply ignore this section.

Notes:

• When selecting a country, make sure you select its parent region too.
• If the Discussion is related to more countries, you can select multiple values.

Error creating thumbnail: File missing

Section 3: Map

If the Discussion is related to a single specific country, you can use this section to geo-referentiate it, so that it appears in the Map of Discussions.

To geo-referentiate the Discussion, go to the field "Enter address here" and type the name of the country the Discussion is about, then click on "Look up coordinates".

Notes:

• You can disregard the field "Coordinates": it will be filled in automatically as you select the country by its name.

Error creating thumbnail: File missing

Section 4: Original message and list of contributors

This section is dedicated to enter author, date and text of the message which started the Discussion, together with the full list of members who contributed to it.

Per field details:

• Posted by (Name Surname): enter Name Surname of the author of the first message. This field autocompletes as you start typing with names of members.
• Posted on: enter the date the first message has been posted to the network.
• Original message: enter the full text of the first message.
• Contributors (add each Name Surname followed by a comma): enter Name Surname of each member who contributed to the Discussion, separated by commas. This field autocompletes as you start typing with names of members.

Notes:

• The field Original message does not feature any user-friendly editor to help you editing with wiki syntax. If you are not used to wiki syntax, you may want to edit this text in the free text section at the bottom of the form, which features a "Rich Editor". See below for instructions on how to use the free text section. - Note: Rich Editor has been temporarily disabled

Error creating thumbnail: File missing

Section 5: Related Discussions

This section allows you to make reference to other Discussions that are someway related to the current one.

To add one or more related Discussions, click on the button "Add another", then start typing the title of the Discussion. Suggestions will show up to make it easier for you to fill in the field correctly.

Notes:

• It is very important that the title of each related Discussion corresponds exactly to its own actual title on the wiki. If you make typos, the link to the Discussion will be broken when you save the page (usually, you can recognize this by the color of the link: in wikis, red links are for non-existing pages).
• It is a good practice to take a look at other Discussions and check if there are any similar to the one you are editing. Adding related Discussions makes the navigation smoother to people looking for information on the wiki.

Image 1: Adding the first related Discussion

Error creating thumbnail: File missing

Image 2: Editing a related Discussion

Error creating thumbnail: File missing

Image 3: Adding/removing related Discussions

Error creating thumbnail: File missing

Section 6: Summary (free text)

The last section of the form is a free text area which you can edit just as you would do with any other page on this wiki.

When you create a new Discussion, this section shows up with some predefined text in it, consisting in an outline aimed to help you editing the summary following a certain structure:

• Under "Summary": a brief introduction to the main discussion points.
• Under "Detailed Description": the meat of the topic - clearly, crisply communicated summary of the topic. Where relevant, a brief story - no more than 1-2 paragraphs - of how this topic has been turned into practice, ideally from the KM4Dev archives? If the example is long, separate into a separate subsection.
• Under "Examples in Application": case studies, practical examples of how the items covered in the discussion are dealt with in everyday life.
• Under "Recommended Resources": websites, publications, articles, general resources shared within the discussion shall be gathered, organized and listed in this section.

Notes:

• You can delete predefined text and substitute it with the text of the summary.
• If there is a paragraph for which no content is available, you can delete the relative paragraph's title.

Rich Editor - temporarily disabled

This section features an user-friendly editor, which you can activate by clicking on "Rich Editor", at the top-left of the free text area:

Rich Editor disabled

The editor helps less experienced users to edit the format of the text, without having to deal with the wiki syntax. The editor works pretty much as Microsoft Office, Google Docs and the majority of WYSIWYG editors: format gets assigned by selecting text and clicking on buttons for bold, italic, etc. And you can immediately see the end result.

Rich Editor enabled

Notes:

• It is a good practice to disable the Rich Editor before saving the page.
• Since this is the only text area in the form which features a Rich Editor, you may want to use it to edit text to be then moved to other sections (for example, the text in the "Original Message" section). To do so, you will have to make sure to either disable the Rich Editor or click on the button displayed below before copying the text you will then paste into another section:

Rich Editor - see wikitext

For more information on how to edit wiki pages, see the Wiki Editing Basics and Tip Page.

Adding individual contributions

In wikis, each page has its own "discussion page", that is a secondary page where people discuss about edits/updates/errors in the primary page. The discussion page is the backstage of a wiki page.

In E-Discussions, the discussion page is where the flow of individual contributions to the E-Discussion is recorded, while the main page is dedicated to host a consolidated summary of the E-Discussion.

• To create a discussion page BEFORE creating its related E-Discussion, type the following into your browser's address bar (substitute "TITLE" with the title of the E-Discussion you want to create):

http://wiki.km4dev.org/Talk:TITLE

• To create a discussion page AFTER the E-Discussion has been prepared, click on the "Discussion" tab on the top left of the E-Discussion's page:

Create a discussion page

This will create an empty page where you will be able to enter all individual contributions to the Discussion, in chronological order, following this outline:

{{Discussion - Talk Header}}

== Name Surname, YEAR/M/D ==

message

== Name Surname, YEAR/M/D ==

message

== Name Surname, YEAR/M/D ==

message

Details:

• "Name Surname" is the name of the author of the individual contribution.
• "YEAR/M/D" is the date the individual contribution has been posted to the network.
• "message" is where you can enter the full text of the individual contribution
• "{{Discussion - Talk Header}}" is a template which generates a navigation bar that will make it easier for users to add new contributions or go back to the Discussion page. Just copy and paste it as it is, but with the Rich Editor disabled.

Notes:

• Only enter the author's message for each individual contribution. Skip quoted messages from other members.
• You can also skip the signature, as the Name Surname of each contributor is already displayed as the title of individual contributions.