wiki:en/doc-guidelines
This application is not used any more and exists only for history. Post new tickets on the Github account.
Cette application n'est plus utilisée, et existe uniquement pour son historique. Postez les nouveaux tickets sur le compte github.
Last modified 5 years ago Last modified on 08/19/09 20:55:40

Documentation Guidelines

Here is a summary of the guidelines for the english documentation. You are free to apply or not these guidelines in the other language.

General writing

There is simple trick that you use when writing documentation. You need to make sure that the content is reader-friendly, so avoid putting to many technical terms: don't talk about the how and the why of Unix sockets in detail when talking of PHP installation, even if they are mentioned in the API. Write your documentation as if the reader remembers only half of what he read on the preceding pages, and as if the user had only a very limited knowledge of technical terms. But be mindful, and don't over-simplify the documentation since advanced users won't like it.

As always, be careful for grammar and spelling mistake. Write in regular, international english and don't use colloquial terms. Always preview your changes, to double check for errors.

Inline code

There are many guidelines for inline code. However, following them will create a consistent look in the documentation

Files and folders

For files and folders referenced inside text, use the inline code syntax. You simply add @@F@ before the path and @@ after. This will make the paths easily identifiable.

@@F@The/path/of/the/file.php@@

Function names

To specify a function name inside a paragraph, add @@M@ before and @@ after. This will make the function name catch the eye easier.

@@M@jelixClass::function@@
@@M@function@@ of the jelixClass

Jelix terms

All Jelix-specific terms or components name inside text should stand out a bit. Therefore, they should be surrounded by @@ before and @@ after.

@@jelix term@@

User defined/redefined component

Any jelix component that is defined or redefined by the user inside the application should be surrounded by @@C@ before and @@ after. This does not include function names, which should always follow the function name guide.

@@C@user defined component@@

(X)HTML content

Any (X)HTML content should be surrounded with @@E@ and @@.

@@E@<html tag>@@

Example code

Example code is code that is used as example, and that could be directly used in a website. First, you need to surround the code with the <code code_type> </code> tags. The most used code types are php, html and ini.

<code html>
<p>A html paragraph</p>
</code>
<code php>
$var = $this->param('var');
</code>
<code ini>
[section]
key = something
</code>

Generic Guidelines

  • Use a single language in the example code. Since most of the documentation was originally a translation from the french docs, examples sometime mix english and french. They should all be edited to include only english.
  • Be consistent in you examples. Use the same examples throughout the whole page. This will make comprehension of the concepts easier.
  • Use 4 spaces to indent the examples. Never use the tab character.
  • Indent the code using the 1TBS coding style.
  • Use clear variable names. Instead of using a variable called $x, use on called $numberOfResultProcessed.
  • Use CamelCase. By enforcing a strict naming convention, code can be consistent.

The current documentation guideline is frozen. Post any changes you might want to the forums and they will maybe be added.