Writing Guide

From EncyclopAtys

Revision as of 17:49, 3 November 2020 by Craftjenn (talk | contribs) (→‎citation, poems...)
Jump to: navigation, search
en:Writing Guide
fr:Guide de rédaction
 
UnderConstruction.png
Translation to review
Don't blame the contributors, but come and help them 😎

Reference text ( Maintained text, used as reference ) :
Notes: (Craftjenn, 2020-11-03)

This writing guide is a “mini-guide for dummies” with a rolistic hue, i.e. built for an encyclopedia written for and by the “[#User or homin|toons]]” (more than by their “"anima"” hiding behind their Karavan interface module [1] by strumming on a shell of arma). This guide focuses more on the art of pages' composition than the how to make articles. However it quickly provides the reader with the basic essentials for him to take control of these fabulous MediaWiki.

  • Wiki tools bar present the tool bars on wikis (small attempt to improve communication - as it's better to use the same vocabulary when asking for help).
  • An other Guide, pore technical is on Wiki Technical Guide. There's some notes on wiki, seen IG (but only in French), and since then the IG browser is better.
#pj-ryzom_wiki is the RC channel to talk about wikis

to start

I would like to write something. What a good idea! But it may have already been written, so the wisest thing is to find out if someone has come before you. And there, oh! nice! either the wiki tells you that the article exists or it shows you:

Search result

...

There were no results matching the query.

Create the page « Trucobolite » on this wiki !

If you hover over the text written in dark red (not here, because I have intentionally not added any link) you will see the name of the page highlight and display "Trucobolite (page does not exist)". All you have to do is click to open a blank page and start the adventure.

It's so simple? Um, almost. Just before you start, follow these tips for choosing a title:

  • Avoid as much as possible articles, plural... be close to a dictionary entry. It is better to write an article about Corsairs than about The Corsairs even though in the end it's like the corsairs as a tribe we want to talk about.
  • If you feel that the article should be written, but perhaps with a similar spelling, you can use the Google search engine by typing the statement:
trucobolite site:http://en.wiki.ryzom.com

And if the page I wanted already exists? Ah! that's another adventure. Later! Now the question is:

Breaking the blank page

To write in a wiki, the easiest way is to write, write, write ...

And so you start ...

After hundreds of characters entered briskly on your keyboard you will take a look at your work, and as everyone advised you you choose the Preview button instead of Save. And, oh, surprise! your text is an inelegant pile of endless words.

As long as you're not used to MediaWiki, you may get some surprising results in the first place. But with very few rules, it is possible to quickly write a good and beautiful text.

Indeed, MediaWiki was designed at a time when wyziwyg was not commonplace. And yet, it wanted to be easily accessible to non-computer scientists, those who work without a mouse, visually impaired ... It was therefore necessary to work as efficiently as possible (that is to say, tiring as little as possible, specialty both Tryker and computer scientists among others) and so, it was necessary to play on simple gestures like repeating the same key to achieve a certain result. But first of all, let's try to see clearly.

Basic formatting

Paragraph

In MediaWiki, a "carriage return" is not a "return to line" let alone a paragraph break. In the spirit, this wiki is very close to HTML. And in the latter, the return to the line has no meaning other than that of making the lines more readable in the source. So, to make a new paragraph, you need two "carriage return" (or a blank line). Here is an example to illustrate these "carriage returns":

This is an example of
a text written on
3 lines.

And this a a new paragraph.
 In case a line begins with a
it gives a very special effect, very useful, but perhaps unexpected in the context.

This will be dsipalyed as

This is an example of a text written on 3 lines.

And this a a new paragraph. 

In case a line begins with a space

it gives a very special effect, very useful, but perhaps unexpected in the context.

Titles

Your text is already more readable, but it probably lacks to be organized. For that, you will want to add titles. Here too the technique is simple, just frame the text with "=" as shown in the following examples, taken from this passage:


==Breaking the blank page==
===Basic formatting===
====Titles====

And, will you tell me, there is no =Title level 1= ? No, this one is reserved for the MediaWiki who uses it to make the title of the page.

Comment and wiki tags

A comment is some text, inserted in the wiki code of a page, that we can only see if we modify the wiki page = it remains invisible to the display (or in other words: only those who have the right to edit this page can see it).

<!-- This is an example of an invisible comment -->

The wiki interprets the wiki code that you enter in a page; it is done to automatically perform a number of tasks depending on the context. For example:

  • before recording a page, it interprets the code (hence the preview, which gives an idea of ​​the silent work done by the wiki, just before saving these codes.) We understand this aspect, with the comments and the nowiki tag)
  • before displaying it (the reading mode via the Page view: it hides the comments, processes the nowiki tag, ... the write mode via the Edit view: it shows the comments...), ...

This help page very often uses the nowiki tag to show wiki code.

What is a tag?
It is a series of characters, used for the structuring of a document and which will be invisible by the final reader. In general (the line break is one of the well-known exceptions) there is an opening tag and a closing tag - HTML follows this logic, and the code wiki has much in common with it. Typically: '''<a_tag>''' bla bla '''</a_tag>'''

With the nowiki tag, as soon as the wiki recognizes the first tag, instead of working as usual, it changes mode until the closing tag. In the wiki toolbar, open the advanced bar to see its icon (just after the numbered lists)

bring out

Well, no, we do not emphasize, we do not highlight! :)

When something is important, you tend to raise your voice or change the tone. One could say that it is the same in writing: it puts in bold character. Needless to say, it's not worth while to raise your voice all the time ... it's tiring.

A convention (but not an obligation) is to always write, before the first title, a summary in which the name of the article appears as soon as possible. This habit is intended to confirm to the reader that it is on the right page, which is very useful when some pages are redirected.

And italics? Basically, we could say that these are quotes and expressions that are out of the current contextual language (honorific title, foreign word, wording ...) and that we could have put in quotation marks. For example, for us atysiens, it could be an OCC expression in the text.

So here is how to produce both types:

'''In bold''' and ''in italics'' and with '''''both'''''.

This will display

In bold and italics and both.

When I told you that you were typing thirty-six times on the same key!

Lists

Well, for sure, now that you know how to write in the wiki, you will want to give recipes, raw materials to extract ... And then, you want it to be done in a quest, in a certain order .. It's easy in MediWiki. To get this:

  • a list item consisting of an ordered sequence
    1. itself composed of a list
      • A
      • B
    2. etc.
  • etc. ...

you need to write that:

*a list item consisting of an ordered sequence
*#itself composed of a list
*#*A
*#*B
*#etc.
*etc. ...

Add an image

For now, we were just text, and yet nothing like an image to clarify a description (describe the fauna and flora without image!) Or just to enhance the reading.

Which image?

Before placing an image on a page of EncyclopAtys, it must have been downloaded beforehand. We strongly advise, before going further, to re-read the EncyclopAtys:General warnings and http://atys.wiki.ryzom.com/wiki/Terms_of_Use

Where to find the pictures?

The images are stored in the COMMONwiki (common to all wikis: French, German etc) :

How to put a personal picture

I found or made an image that I want to insert in an EncyclopAtys article. (Warning: the image must be under a free license like the GFDL. )

To import the image, you have to choose from the menu Tools the command Import a file" and follow the instructions.

Click on "Browse" to choose the image that is on your machine, it can be useful to indicate keywords and category in Summary; validate at the bottom in click "Unload file" (wait for the sending of the image on the servers of Atys).

The image has been sent (we no longer see the instructions for help with insertion). However, it must now be inserted into the wiki code (copy the exact name of the file, eg "File: Barreswiki.png" go to the next step).

The images are hosted in the Common (URL address that how in atys: https://atys.wiki.ryzom.com/wiki/Home). More on Tips for categorizing an Image.

Inserting an image, wiki code

To insert an image, just write: [[file:Name of the picture | thumb | where | size | alt=Textual Alternative | Legend]]. For example, to display the 2 images of this paragraph, write:

[[file:Dummy.png|thumb|right|alt=A strange sphere, ex thumb right|The emblem of the ASA, ex thumb right]]
[[file:Dummy.png|64px|alt=A strange sphere, ex 64|The emblem of the ASA, ex 64]]

A strange sphere, ex thumb right
The emblem of the ASA, ex thumb right

A strange sphere, ex 64 where the Name of the picture is preceded by the prefix «file:». The other parameters are optional.

More on https://www.mediawiki.org/wiki/Help:Images#Link_behavior

Galleries

If we have several images, we can use the "file gallery" (on the toolbar in edit mode of the wiki, the icon just to the right of "Insert").

This makes it easier to read/edit the wiki code because it adds gallery tags; thus, each image will be on a line (in the wiki code), with a simple syntax: filename.jpg the "vertical bar" (AltGr + 6) and a description:

  • Toolbar in edit mode on the wiki

  • an other image

  • misnamed, because does not allow to send an image, but just add it to the page

Links

There are several kinds of possible links in a MediaWiki document. Here is the list:

Note that the letters attached to this type of link unite to form a single word: flyners. We can of course rename to adapt to the context: planiant plant ...

Here is the wiki code:


* internal link as [[User Manual]]
Note that the letters attached to this type of link unite to form a single word: [[flyner]]s.
We can of course rename to adapt to the context: [[flyner|planiant plant]] ...
* link to a title [[User Manual#Web Applications]] or on title (same page) [[#Galleries|Gallery's title on this page]]
* external link is very simple, as in https://ryzom.silenda.de but if you want a more elegant presentation you can use [https://ballisticmystix.net the website ballistic mystix] .
* And the reference which is a link to a note <ref>example of note</ref> at the bottom of the page, as can be seen on this line.
* Links to other wikis (interwiki links): add the language before, such for common [[:atys:Category:User work|User work images]], or to the French version of this guide: [[:fr:Guide de rédaction]].

And if you see the following message at the bottom of your page, do not worry, we'll see that right away...

Reference error : some <ref> exists, but no <references/> found.


To link to a wiki page on an other wiki, see Help:Interwiki.

Other tips

citation, poems...

  • "quote tags" <q> blblbl </q>. The enclosed text will appear with an italic serif font withi appropriate quote (language dependant) characters. An example: blblbl
  • "poem tags" is a wiki extension. <poem> Looooooooooooooooooooooooooooooong text or not so long </poem> will display:

 Looooooooooooooooooooooooooooooong text or not so long

The Poem extension allows easy formatting of poems and similar material within Wikitext. Once the extension is enabled, you can put any block of text within <poem></poem> tags, which has the following effects:
  • All newlines are preserved by converting them into <br /> tags
  • The block of text is enclosed in <p>...</p> tags (as well as a div of class "poem")
  • Colons at the beginning of a line are converted into 1 em indentation
  • Spaces at the beginning of a line are preserved and no longer invoke the <pre> tag (a must to have paragraph indentation)
  • The extension preserves wikilinks, bolding, etc. if they are present in the poem.
  • "center tags" anything between these tags will be centered to the page <center> blblbl </center>.
    • Note that floating images or tables reduce page size, thus the {{clear}} template is often useful to force text to appear under an image.
    • Note also that you may need to add a couple of cente tags if a new line breaks it. It isn't necessary if you use only
      to separate different lines.
  • emdash space (CTRL then space, or U+2212 U+0020) is useful, often combined with quote tags to separate the sentences of in dialogs


Examples: The_Kitin_Song, Tears_of_Serenity, A_Flyner_Escape

Useful links (Special pages)

Pages too long can be an issue IG

Note: long/heavy page is an issue, if user read wiki from the game, as the game browser is limited in memory (for ex, User Manual :( Therefore, for some pages, it would be better to check IG if they are fully displayed.


for EN it's, in Feb 2020:
(hist) ‎User Manual‎ [87,963 bytes]
(hist) ‎Paul C. R. Monk – Bloomtree ‎[75,959 bytes]
Story of a Young Fyros ‎[61,565 bytes]
(hist) ‎Categorization ‎[60,455 bytes] -> not an issue as it's NOT for helping homins but for wiki contributors
(hist) ‎Chapter II - Vigils in the Marauder Camp ‎[58,750 bytes]

IG, the Lore don't comes from here (but from an other tool, and through a service who cut some html/css code). The game's internal browser has a very limited memory (css issues too). User Manual v3 can't be read IG because it's too long and too big. The User Manual, faq and help should be quite light. The wikis are quite bad on a cell phone too...

A solution: use titles, and below the title, create a sub page.

  • More on Help:Transclusion (about partial transclusion tags noinclude, includeonly and onlyincude, and template for the wiki In Game too).

Sorted array

An ex: fr:Emotes

{|cellspacing="0" cellpadding="5" border="1" style="text-align:left;" class="sortable" |-bgcolor="#eee" style="color:black;" !Titre col 1 !Titre col 2 !Titre col 3 |- |}

And to finish

You want to save your page. Wait a sec! Sure it's finish? Don't forget the final touch.

Notes

At the end of an article you will often find the following information, including the famous <references/> which indicates where to display the notes you created with the <ref>...</ref> seen above.


==References==
===See as well===
*[Somewhere on the web...]
*[[Or in this encyclopedia...]]
===Remarks===
*Specialists in : [[PC]], [[NPC]]
*... : ...
===Sources===
*{{Source
 |Langue=[[:Category:Ja|]]
 |Auteur=[[user:Rajaaar|]] and [[user:Zorroargh|Zo'ro Argh]]
 |Perso=PC
 |Guilde=[[Guilde:Hoodo|]]
 |Site=Registre Des Guildes (Ryzom Community Forum-Aniro)
 |Date=JY 2557
 |Page=Hoodo, les chercheurs de Symbiose
 |URL=http://atys.ryzom.com/start/app_forum.php?page=topic/view/8293
 }}
*{{Source
 |Auteur=Derry O'Darren
 |Perso=chroniqueur tryker
 |Site=Les chroniques d'Atys
 |Date=vers 2486 (JY)
 |Page=Chronique relatant un épisode de la vie de Rosen Ba'Darins
 |URL=http://atys.ryzom.com/projects/pubfr/wiki/C_EvasionEnFlyner
 }}

===Notes===
<references/>

Courtesy

An encyclopedia aims above all to synthesize all fields of knowledge (Atys). To achieve this, the articles are inspired from various sources. Beyond the encyclopedic aspect and the weaving of the Web, which recommends citing the sources, there is also the elegance of the recognition of the work of an author.

Preview and save

Previewing is also a form of courtesy. It not only makes it possible to verify that everything is correct before validating, but also to avoid that the modification histories fill up unnecessarily. Of course, Jena will not throw you into the hands of Kamis, or they will plunge you into the Goo if after validating your backup you find that you have missed some errors.

Note: if you get the message (which appears often, because wikis don't like people changing the same page too often - it's not related to the capacity of your PCs or the quality of your connection to the web), save the page again - and you're done!

Sorry! We could not process your edit due to a loss of session data. You might have been logged out. Please verify that you're still logged in and try again. If it still does not work, try logging out and logging back in, and check that your browser allows cookies from this site.

Importance

If this is the case, you then have to check the Minor modification button. This allows you to correct an article, make intermediate changes, etc. Because of this, you can hide minor changes when you make a search for changes. Think of the administrators!

Signature

Lastly, this is not where you will have to do it, but since this is the last word in this paragraph and it's very important when writing to someone or in the article-related discussion page, type always as an end point: ~~~~.

This serves as a dated signature, which is additionally a link to your personal page.

To add a link on this wiki to your RC adress, the wiki code is [https://chat.ryzom.com/direct/YourName YourName on RC] or using an image Private message on RC [[File:RClogo211905.png|Private message on RC|link=https://chat.ryzom.com/direct/YourName]]

as here Contact Craftjenn on RC


Very useful for wiki translators:

  1. explanation of the inter-wiki signing issue, for example... Let's say my profile is on the English wiki (User:MyName).
    • If, on a page of the French wiki (or other language, such DE, ES, RU), I use my signature (with the code 16:10, 3 March 2020 (CET))...
    • it will put a link on the discussion page of the profile User:MyName, which is on the English wiki
    • Then there are two cases:
      • either I don't have a profile created on the French wiki, and the talk link will be red (the page doesn't exist)
      • either I created a profile on the French wiki (talk link in blue) - but I wouldn't be notified on the English wiki, if I usually don't go much on the French wiki. So, I'll have to think about checking the 2 (or more) talk pages regularly :(
  2. There are several solutions: Zo's one and Craftjenn's one. The simplest is to use RC and that's what is presented here.
    • On the top right of the screen: Preferences, (1st tab where we arrive), part Signature :
    • "New signature": CraftJenn, Ranger of the Circle of the Wood of Almati ( [https://chat.ryzom.com/direct/Craftjenn on RC] )
    • check "Treat the signature as wikittext (no automatic link)".

The art of writing an article

A wiki is a collaborative work with many hands and everyone knows that there are as many ideas as homins. Also, it is advisable to write as much as possible according to the "Principle of least surprise", that is to say that the reader finds the same schemas from one page to the other despite the fact that it was written by different homins.

MediaWiki offers several tools and default behavior. For example, as soon as you have 4 titles, a summary is automatically generated above the second title of the page (the title of the page itself, level 1, being the first).

Schemas and templates : about navigation toolbars, templates... To update and translate from French.

OOC: Out of character

You know the minimum to get by. Of course you will have to search stuffs. This will look like the work of Surveys of Mission Raw Materials which will be more and more valuable. There is one last point you will not find elsewhere: "How to elegantly introduce OOC in roleplay (RP) articles?"

Dates and time

Please use the Atysian dates. More on Time and there's a tool to convert dates on https://ryzom.kervala.net/time.php?shard=atys

⇒ in notes

In the roleplay text, the Atysian date Holeth, Winderly 24, 1st AC 2603 [3]

The code is
'''Holeth, Winderly 24, 1st AC 2603''' <ref>OOC: 2019-04-15</ref> and will be displayed down page as

↑ OOC: 2019-04-15

⇒ in the text

For a longer explanatory note, you can create an OOC paragraph at the end of the article that looks like this paragraph. 

{{OOC|short comment|Some quite long text}}

will NOT give the colored section: it seems this Template don't exists



⇒ in a tabbed page

As in APageRPandOOC


Categorise your OOC pages

This category doesn't exists in the English wiki. Thanks to use for spoilers Category:Mysteries

Portals

Portals contain topics and often tabs. In general, the portal and the sub-pages and headings are locked at prime access to avoid accidental (even malicious) changes. The source of the portal then often has two parts, quite small since everything is outside the portal. Thus, if we take the matis portal, we see at the top, the tabs code and at the bottom the code of the rubrics.

Of course, we could have changed the order of the tabs. When correcting (or creating) tabs, care must be taken to copy the complete tab structure in each of them to remain visually consistent. And to correct the different pages designated by the tabs, it will go directly to the page indicated by the URL. The simplest is to click on the title indicated on the tab.

topics

More for reasons of elegance than of protection (for that it is enough to change the rights of writing), the headings are not editable from the edit link which accompanies each title.

This is a title whose content is editable by clicking on the associated link... [edit]

If you don't want to see the "[edit]" link, just add in the page "__NOEDITSECTION__".

Often, for the same reasons, we do not want to see tables of matter to embed themselves in the page: add "__NOTOC__".

But if you want to change the content of these pages, how can you do so since there is no link?

Here's my tip:

The pages that appear in the structures of a portal are of this type: 

 <!-- ==============LIGHT ON ================ -->
 !{{ContentBox
  |title= {{3DText|group=tryker|3D=inset|text=General presentation}}<!-- default=Spotlight on}}-->
  |palette=tryker
  |image= Tryker emblem.png<!-- default=Zor emblem.png-->
  |content= {{:Tryker}}
<!--{{:Featured article/Tryker}}

To work on Featured article/Tryker, I copy somewhere in my personal page "{{Featured article/Tryker}}" then I change the braces in hooks and, as braces are for templates in mediaWiki, prefix with template, it should gives "[[Template:Featured article/Tryker]]" - this is the link I will use to change the Tryker page (and then the Tryker portal).

And after...

Above all, what to do then if you come across the case or a page exists with another title. For example, you wanted to write Corsair but The Corsairs already exists. Well, this has been planned in the MediaWiki: you can redirect a page to an other one: write in the page Corsaire (that you wanted to create) 

#REDIRECT [[The Corsairs]]

You are now ready not only to write, but also to modify the existing one. And that's not always easy either. You can usually add the flourishes that have been taught above especially at least one category (the good), links, references ... They are often forgotten by the editors of passage. Making small corrections is always welcome but sometimes if the content seems to you wrong it is better to start discussing when possible with the author or in the article's discussion page. Otherwise, it may happen that the writing of the article is transformed in PvP.

For translation codes, and translating on wiki, see WikiTrad-EN.

Templates

Template is for repetitive stuff. For example, a navigation bar on several pages: create Template:My_Nav (with the links) and use with {{My_nav}} on pages (each time you change Template:My_Nav, all page who have code {{My_nav}} will use the last updated Template:My_Nav).

See for ex Category:Navigation_templates

If you create your own Templates, thanks to add the category [[Category:User Templates]]. To get an idea of some examples: Category:User Templates

Links

#pj-ryzom_wiki is the RC channel to talk about wikis


A selection of official links


For users

rename and move

advanced stuff


Other useful links:

Top






Last version 2023-10-18•ᐒ
  1. ↑ A “Karavan interface module” is named computer IRL
  2. ↑ example of note
  3. ↑ OOC: 2019-04-15
Retrieved from "https://en.wiki.ryzom.com/w/index.php?title=Writing_Guide&oldid=39775"