Help:Writing

From phpCMS

Jump to: navigation, search

Contents

[edit] Writing Guidelines

This help page contains general information about the writing style in this documentation wiki.


[edit] Pagenames

Use short pagenames, longer ones are a source of errors and not easy for using in links.

Example: 

bad: How to enable the Online Editor - better: Online Editor

You can use the first headline in the page to give a more descriptive chapter name.

[edit] Headlines

Consistent use of structuring the docu pages with headlines will be very useful for a later transformation into a PDF-document. As every page name is set to <h1> by the wiki software, please use <h2> for the first headline in the page and only for the first headline which is somewhat like the 'chapter title'.

A good example page is System_requirements or CMS_Introduction.

[edit] Formal Style

Currently there's a very mixed style in how the user's been adressed (formal like 'The file extensions can be chosen arbitrarily' or personal like 'In such a template you define variables'). Please use the formal style which fits better for a technical documentation. This regards the five main parts User Docu, Plugin Docu, Developer Docu, FAQs, Tutorials.

(Note: And yes, in these wiki's community pages we use the personal style ;-) )

Examples: 

Use As mentioned before, a webserver is needed instead of 
As mentioned before, you need a webserver
Or In such a template variables can be defined instead of 
In such a template you define variables

[edit] Naming Conventions

- Some naming conventions, e. g. 'predefined tags' or 'placeholder' as Iggi mentioned - and of course the naming conventions for 'chapter', 'this docu' instead of 'this wiki' etc.

[edit] New Pages

Please make sure that new pages contain the following important parts:

  1. A navigation (have a look at the navigational templates at this help page)
  2. If a page exists in more than one language (e. g. the FAQ Entries or MiniHowTos), please add a suitable link (you can use a template as well).
  3. At least one category - at the moment it's enough to use the main category (see also: Help:Categories)
  4. Get listed on the according MainPage, for example the User Documentation MainPage for new pages in the User docu.

to be continued

Retrieved from "http://docs.phpcms.de/index.php/Help:Writing"
Personal tools