So you're willing to contribute documentation to the community site ? Great.
But you're not sure how to do it well ? This page is here to guide you.
The single most important rule
The single most important rule is: "
Pages can always be corrected, and it is usually much easier to
fix an existing page that to create it in the first place, so
if you refrain from contributing because you don't know how,
just stop refraining : create that page you think the
community needs, and ask others to improve it
once it exists. If you don't know how to ask, just
contact the site maintainer for help.
Writing for a community web site
You must keep in mind that not all site readers have a nice
30" display : many of them still have resolutions of 1024x768
or even narrower. Given the use of a three-column layout on
the site, this means that no code should be wider than
70 columns : wrap long lines where it makes sense, to avoid
automatic wrapping that can ruin the readability of your code.
Wrapping every PHP-GTK symbol in the text in a
<code> element makes them stand out and eases reading.
At some point, it may also allows improved search features,
so it is important to add these wrappings.
Of course, profanity and adult content would be out of place,
and standards for appreciating the appropriateness of content
vary wildly around the world, so it is always better to err on
the side of caution to avoid alienating readers, and depriving
PHP-GTK from them.
Pages contributed are meant to be edited in community,
so do not expect your content to stay unchanged (that's why
you probably have a blog, too, don't you ?) :
pages may be edited over time by other contributors to
improve their quality, reclassify them as the site structure changes,
and so on. You will always be recorded as the original author,
Licensing : by registering to the site, you
have agreed to only contribute content you rightfully owned
the rights to, and grant a Creative Commons "CC-BY-SA 2.0"
license to the site owners, who in turn grant the same license to
any user. This means you are legally bound not to submit any
content under another license, including GPL, MPL. You may,
however, point to it : if the link is accurate and points to useful
information, it won't be removed as spam.
The site strives to be XHMTL 1.0 strict. This can only be
achieved if contributors type in proper XHTML fragments instead
of any old HTML tag soup. Most errors are actually quite simple
to avoid. Here is a short list of recommendations:
- closing tags: every element ("tag") must have a
matching closing tag. That is, if you start a
paragraph, it must end with a
closing tag. Empty elements like line breaks or horizontal rows
include their closure as
<br /> and
- tags are lower-case: element names ("tags") are
lower case, like
<ul>, not upper case
<UL> as they were in HTML.
- attributes are double-quoted and always have a value:
while in HTML you could write things like:
<OPTION SELECTED>foo, XHTML requires you
to code like:
lowercase, attribute without a value in HTML takes its name as
a value in XHTML, and attribute values are wrapped in double
quotes. And, of course, every element has a closing tag.
- images needs an
alt attribute : this is
needed for XHMTL validation but is also important to help
search engines index your images.
- chimp attractors are dead: early HTML elements like
and mostly anything visual has no place in XHTML: styling has
to be done in CSS. For most needs, this means don't even
worry about look: the site theme will take care of that for you.
See exceptions below.
- paragraphs don't nest block content: although this may
seem counter intuitive, you can't nest a paragraph
<p>), a preformatted block
<pre>) or a list, or for that matter
any "block" content in the CSS sense, within a paragraph.
Only "inline" content, like <code>, or
<img ... /> is allowed within an paragraph.
- nested lists are a bit complicated: try to avoid them. Lists
can be nested, but the syntax is a bit awkward. If you're
unsure how to do it, just ask someone, or don't use nesting.
For some pages, like application pages,
it is recommended that you derive your page content from
an existing skeleton, in order for all pages of the same group
to look the same, making it easier on the reader.
For this reason, the appropriate skeleton is automagically
prefilled when you create an application page. You can also check
the skeleton on the skeleton
for application registration description page.
PHP coding style
Using a consistent coding style for all PHP fragments you
submit makes it easier on site users : look at the existing hints
in the handbooks to write your
examples under the same conventions.
You can input PHP source code blocks by wrapping them in
<?php ... ?> : the code will automatically have its syntax
highlighted much like on php.net
You can input other languages as code blocks by wrapping
them in a
pre element. Like PHP blocks, there
are blocks, so they do no got within a paragraph,
but stand on their own. If you want to embed code inline,
you can use the
code element, which will
automatically convert < and > so you don't have to fix them