Author guidelines
Concise usage guide for contributors to the Grand SmartEiffel Book.
Everyone can freely participate in the creation of the Grand SmartEiffel Book on the condition that they respect the rules and the objectives presented below.
Objectives of the SmartEiffel Wiki
Beyond being a place of research, exchange and sharing of information, the principle objective of the SmartEiffelWiki consists of producing a real book that can be printed, if desired, on paper. The program capable of verifying and then automatically extracting the Grand SmartEiffel Book doesn't exist yet, but if we follow a few conventions and editing rules that will become possible. Of course, the Grand SmartEiffel Book will always be available in electronic form.
The topics addressed (and what should be addressed) in the Grand Book
First and foremost, that which concerns Eiffel and SmartEiffel. Without pretending otherwise, it's a matter of promoting Eiffel as well as programming with contracts in Eiffel. And equally it's to educate about Eiffel and to make Eiffel known. All topics tied to Software Engineering are equally welcome in the Grand SmartEiffel Book: testing techniques with Eiffel, program validation with Eiffel, object oriented programming concepts with Eiffel, (etc. with Eiffel).
If the topic that you wish to address in the Grand SmartEiffel Book doesn't have anything to do with Eiffel, don't be surprised if perchance your article is rejected. You have been warned!
Conventions that we should follow
A certain number of conventions to follow have already been mentioned in the FAQ of the Grand SmartEiffel Book. The conventions and rules which follow should be equally respected.
Place each page in the "Table of contents"
Except for purely interactive pages, the vast majority of pages should find their place in the "Table of contents" page. In fact, only the pages referenced in the "Table of contents" will become part of the printed version of the Grand SmartEiffel Book.
Of course, a Wiki is by its nature a place of discussion and exchange. Certain pages should therefore be utilized for these interactions and exchanges and should not be included in the Grand SmartEiffel Book. So, the pages of the SmartEiffelWiki will be classified into two categories. The Book category for pages to go into the Grand SmartEiffel Book. The Community category for pages intended, for example, for news, discussions and/or exchanges in progress.
Using English as the pivot language
Besides page names, it is simpler to always use the same language, and so to use English, for all similar page items like navigation tags. This is a good example with respect to this rule. We note that following this rule is nearly as important as following the rule for having page names in English. Like page names, navigation tags can also be made part of the URL and so also serve as a means of correspondence between different translations.
Avoid external links
Bearing in mind that we wish to be able to print the book, it is preferable to limit the use of external links as much as possible. We will use internal links as much as possible.
Linking between different languages
It's up to you whether we have a translation in your favorite language. Nevertheless, it is desirable to always ensure that a minimum of linkage exists between pages in different languages. Of course, the utility that will be responsible for producing the paper document derived from the on-line Grand SmartEiffel book will be capable of letting us know that, for example, section numbers in the French version aren't in agreement with the section numbers in the English version. Certainly, the utility will be able to warn us of the error, but it would be a day or two (or more) before one of us would get around to making the correction ... manually. It's therefore asked that each of us use without exception the radio buttons that permit going between one language in order to minimize the amount of manual rework needed later.
Corrections concerning style
Of course, it is not always necessary to ask the author's permission to correct spelling or an error on a page!
With regard to changes converning style or the turn of a phrase, we propose to adopt a preference for a style that is relatively neutral and fairly simple, above all as clear as possible, and finally, not too pedantic. Don't lose the point of view that the goal of the Grand SmartEiffel Book is to promote and educate about Eiffel and not to be a candidate for the Pulitzer prize.
Finally, it's good to keep in mind that it's always possible to return later to make style modifications with a few clicks of the mouse. The simplest means to convince an author of the pertinence of a modification often consists of making the change directly in the text.
To finish, we note that a bit of humor never did anyone any harm. It's up to you to find your own unique writing style.
Bibliographical References
The page that contains the bibliographic references must be exactly the same for all languages: same number of entries, identical tags, and classification order completely identical. Here is the format that is used in the text of [ETL 1992] for citations.
The manual index and the glossary
The manual index as well as the glossary are understood to be special pages because they are not in the same order when one changes languages. For example, the glossary is put into alphabetical order according to the language of the page; the terms defined are not put into the same order for all languages.
That being so, like for the other pages, the navigation tags must be common. For example, there must be as many navigation tags in the French glossary as in the English glossary. Like everywhere else, navigation tags are always in English.
In case of any sort of conflict between authors
In the case of multiple authors not being in agreement among themselves as to what should be written, they must continue to discuss among themselves as well as with the entire community in order to arrive at a consensus.
In the event of an impasse, the SmartEiffel team has the final say as to what decision to make or what to do.
Finally, if the SmartEiffel team itself cannot come to a consensus, Dominique Colnet has the last word.
Final rule
Don't hesitate to complete or amend these rules and conventions. And above all, thanks in advance for your participation to the Grand SmartEiffel Book.