Good documentation is at the heart of a good project. The Enlightenment Documentation Contribution Guide is designed to offer advice on how to write and format documentation pertaining to the Enlightenment Project, including the use of languages, layout, and terminology.
This document is aimed at writers, editors, and developers seeking to contribute to the Enlightenment Project. The Enlightenment Documentation Contribution Guide can also be used by Enlightenment Project users as a means of clarifying existing documentation.
To contribute documentation to the Enlightenment Project you will need an account in DokuWiki, the content management system (CMS) which drives the website. If you do not have one register for an account before working on any documentation.
You should also have passing familiarity with the PHP Markdown Extra markup language and the Enlightenment Documentation Structure.
Although the Enlightenment Project documentation is written by contributors from around the world working in a range of languages, all published documentation must be written in American English and in the second person active voice, present tense. If using a text editor with spell-checking capabilities, please install an American English dictionary. Additionally, treat the Enlightenment Foundation Libraries (EFL) as a collective noun and refer to it as a singular entity using "is" rather than "are".
The documentation is formatted using PHP Markdown Extra, a markup language based on work carried out by John Gruber in 2004. Markdown is designed to allow for human-readable plain text files which can also contain formatting for display in web browsers as rich text. PHP Markdown Extra extends the specification with additional features such as pipe-based table layout.
For those unfamiliar with Markdown, a cheat sheet provides a handy reference for the syntax of the base language while the official PHP Markdown Extra site has details on its extensions. All documentation for the Enlightenment Project should be produced in PHP Markdown Extra format; selected older documentation may be presented in DokuWiki format, but if edited should be recreated in PHP Markdown Extra format.
PHP Markdown Extra files should be created as UTF-8 text with UNIX line endings and their contents pasted into the DokuWiki engine for format verification and publication.
All documentation should include a preface containing the page title for processing by the DokuWiki platform. Details on this preface format can be found in the Documentation Layout section below.
The Enlightenment Project documentation uses a series of namespaces, detailed below.
More detail on these namespaces and their sub-spaces can be found on the Document Structure page.
Files added to the Enlightenment Project documentation collection should be categorized using a directory-style layout. Long filenames should be avoided: the naming convention should use about/area/file.md rather than about-area-file.md so that files relating to similar topics are properly grouped together.
Do not use capital letters or special characters in filenames; stick with standard ASCII characters which can be properly represented in a URL/URI without encoding. Create pages using the title with dash characters (-) in place of spaces, then end the filename with a .md extension.
Each page of the documentation is presented as a single Markdown file. The layout of each page is as follows:
---
~~Title: Enter Title Here~~
---
# Title #
INTRODUCTION
## Prerequisites ##
Include this section if the document requires that the reader has read a previous document or, for practical exercises, that the reader has particular software available.
## Sub-Headings ##
BODY
### Sub-Sub Headings ###
MORE BODY
## Further Reading ##
List of URLs to pages with additional information; these can be follow-on topics, such as in the case of programming tutorials, or supporting documentation.The DokuWiki preface requires the page title formatted as ~~Title: Enter Title Here~~. This should be located at the very start of the document, between a line containing nothing but three dash characters (-) and a line containing another three dash characters. Leave a blank line after this, then begin your PHP Markdown Extra on Line 4.
A blank line should be present between headings, paragraphs, code blocks, and any other part of the document. Headings and sub-headings should be written in Title Case and gerund form ("Adding an X" rather than "Add an X"), and should use the terminated form of Markdown's header format: ## Heading ## rather than ## Heading.
Do not insert hard line breaks as you reach column 80 or the edge of your text editor window; allow your text editor to wrap longer lines for ease of display, but ensure that they are saved without linebreaks before submitting a document or edit.
If using a text editor with user-selectable typefaces, please use a monospace font to ensure proper formatting and layout. If using a rich-text editor to create documentation, please turn off any symbol-replacement functionality. In particular, ensure that 'Smart Quotes' are not used: documentation should be written using straight quotes only, i.e. ' and ". Likewise, use only a standard straight-quote-style apostrophe character - ' - rather than a backtick or other angled character. When quoting something, always use double quotes. If writing an aside - like this - use a single dash character.
All headings and sub-headings will be automatically turned into anchors for in-document links and any automatically generated table of contents and navigation functionality. To link to these sections, use Markdown syntax:
[Text of the Link](#Name_of_the_Section)Note that the anchor has underscore characters (_) in place of spaces; a link created using spaces will not function. The space between the formatting characters of a header and the header name (## Header ##) does not count; only the spaces between words of multi-word headings need to be replaced with underscore characters.
To link to a heading in another document simply include the document filename or, if outside the current namespace, the absolute path to the document:
[Text of the Link](filename.md#Name_of_the_Section)Other links should be inserted using standard Markdown syntax:
[Text of the Link](http://www.example.com)Links to documents within the same namespace should use relative paths; links outside the namespace or to external sites should use absolute paths.
If adding a collection of links to a document, such as in the Further Reading sub-section, use Markdown's Definition List format:
[Text of the Link](http://www.example.com)
: Text describing the contents of the linked page.
[Text of the Link](http://www.example.org)
: Text describing the contents of the linked page.Code extracts inside documentation should be placed within a code block to ensure proper formatting. Where possible, use Markdown's syntax highlighting feature to increase readability. For instance, a C-language code extract should be written as:
```c
if (!p) return;
if (!p) return -EINVAL;
```This will produce easily readable, highlighted code as below:
if (!p) return;
if (!p) return -EINVAL;Where a code block contains extracts from a larger program it should follow the indentation of the main program.
Where referencing code within a paragraph of documentation, use paired double-backticks (``) to format the reference as in-line code. Writing ``-EINVAL;``, for example, will render as -EINVAL;.
When referencing a method in a document always include the parentheses that go with it: efl_add() rather than efl_add, for example.
For information on the formatting of the code itself, please consult the Coding Conventions Guide.
Selected documentation data are better presented in tabular form, rather than as a bulleted or numbered list. Where tables are required, the PHP Markdown Extra table format should be applied as below using the secondary table format with leading and trailing pipe characters.
| First Header | Second Header |
| -------------- | -------------- |
| Content Cell 1 | Content Cell 2 |
| Content Cell 3 | Content Cell 4 |This will render as:
| First Header | Second Header |
|---|---|
| Content Cell 1 | Content Cell 2 |
| Content Cell 3 | Content Cell 4 |
Please take care to ensure that your tables are laid out so as to be neat when viewed in plain-text form, to assist with document portability. In particular, ensure that your pipes line up correctly.
All text table elements should be left-aligned as standard; number should be right-aligned by suffixing a colon character (:). The Markdown rendering engine will take care of any formatting which needs to be applied to table elements such as headers; do not apply any formatting manually.
If using code elements in a table, such as for API calls, wrap the code in double-backtick characters (``).
| First Header | Second Header |
| ---------------- | ------------------- |
| ``Code extract`` | Plain-text contents |This will render neatly as:
| First Header | Second Header |
|---|---|
Code extract |
Plain-text contents |
Images, including screenshots, should be inserted into the document as a Markdown-syntax image tag with a blank line above and below:
Where possible, use lossless versions of image files. Vector images should be inserted as Scalable Vector Graphics (SVG), while bitmap files should be inserted as Portable Network Graphics (PNG). In either case, resize large images and compress the resulting files before uploading them using the DokuWiki Media Manager. When uploading an image, please make sure to select the correct namespace first.
Always use relative paths when creating an image link. Do not embed external images from other websites.
If a document requires a note, warning, or other callout, use the Markdown blockquote syntax with an emboldened and capitalized header followed by a colon as per:
> **NOTE:**
> Insert the text of the note here as a single paragraph with no linebreaks.This will render as:
NOTE: Insert the text of the note here as a single paragraph with no linebreaks.
Applicable callout types are: NOTE and WARNING.
Lists should be formatted as unordered bullet-points, except where a numbered list would make more sense such as when referring to numbered sections of an image or table. For bullet points, use the following formatting with sub-lists indented by two spaces each:
* List Item One
* Sub-Item One Point One
* List Item Two
* List Item Threewhich will render as:
For numbered lists, use the following formatting:
1. List Item One
2. List Item Two
3. List Item Threewhich will render as:
Note that although Markdown does not require the numbers to be in the right order, only that a number is present at the start of each list entry, all numbered lists should use the correctly-ordered numbers so the lists display correctly when viewed as plain text.
At present, sub-lists are only correctly rendered in unordered bullet list format and will not display correctly in numbered list format.
Documentation namespaces should have navigation sidebars, permanent boxes visible on all pages providing quick navigation through that namespace. These navigation elements are controlled by a page named "navigation" in the root of each top level namespace. Each navigation file is a hierarchical list of links for the entire namespace tree - child pages will be displayed when the parent page is being displayed so we can keep the navigation manageable.
When creating a new document in a namespace, or moving an existing document, always update the navigation file. To do so, find the right file for the namespace: the navigation file for the "/contrib" namespace, for example, is "/contrib/navigation".
The format of a sidebar is shown below:
* [[/contrib/start]]
* [[/contrib/report-bug.md]]
* [[/contrib/efl-debug]]
* [[/contrib/enlightenment-debug.md]]
* [[/contrib/devs/ | EFL Developer guide]]
* [[/contrib/devs/git-guide.md]]
* [[/contrib/docs/documentation-guide.md]]
* [[/contrib/docs/ | Documentation]]
* [[/contrib/docs/eo-guide | Eolian Documentation Guide]]
* [[/contrib/docs/eo | Eolian File Format]]Note that these pages are in DokuWiki markup format, not Markdown Extra. Each entry in the navigation should be in the form of a DokuWiki link; if the page to which you are linking has the DokuWiki title set in the frontmatter this will be pulled through and used as the display text. To override this title, or to link to a page which does not yet exist and thus has no title, use a pipe character followed by your preferred link text.
NOTE: Always include the
.mdextension when linking to a page in Markdown format. Although the link will work without it, DokuWiki will not be able to retrieve the title tag for sidebar display.
Programming tutorials, and other hands-on educational documentation, require a specific approach in order to be both accessible and informative. As with all other documentation, programming tutorials must be written in American English and in the second person active voice, present tense. If using a text editor with spell-checking capabilities, please install an American English dictionary. Additionally, treat the Enlightenment Foundation Libraries (EFL) as a collective noun and refer to it as a singular entity using "is" rather than "are".
Particular care should be taken that programming tutorials adhere to the guidelines in the Code Formatting section of this guide, and any freshly-written code follows the Coding Conventions.
The template below demonstrates a rough approach to which you should adhere where possible:
---
~~Title: Tutorial N: Program Name~~
---
# Tutorial N: Program Name #
Brief introduction describing the program, its purpose, and what it aims to teach you about EFL.
## Prerequisites ##
Anything the user should have already installed, along with links to tutorials they should have already read.
## Step One: Description ##
```language
Functional Code Block 1
```
Description of Code Block 1's function, including but not limited to: what it does, why it is required, and any EFL-specific information regarding its purpose as it may differ from non-EFL programs.
## Step Two: Description ##
```language
[...]
Code Block 2
[...]
```
Description of Code Block 2's function, including but not limited to: what it does, why it is required, and any EFL-specific information regarding its purpose as it may differ from non-EFL programs. Keep adding functional code blocks until...
## The Complete Program ##
```language
Functional Code Block 1
Functional Code Block 2
[...]
Functional Code Block N
```
Add any notes about the layout of the program, such as indentation which has been added or anything which has differed from the above Code Blocks.
## Summary ##
Summarize the documentation here, highlighting what the reader should have learned.
## Troubleshooting ##
Highlight common issues specific to EFL or the program here; there is no need to highlight generic coding issues like forgetting semicolons.
## Resources ##
Links to useful files, including a copy of the program and any required additional files, plus external documentation such as Wiki pages offering greater detail on topics covered where appropriate.
## Additional Notes ##
Any additional notes, such as expanded functionality not covered in the core program.
## What Next ##
Link to the next guide with a brief description of how it builds on the current guide.Building the program up step-by-step in minimum-viable functional blocks like this provides a welcoming experience and ensures that the reader understands the core concepts properly. It also makes the overall program seem less intimidating than if it were presented in completed form at the beginning then broken down piece-by-piece.
When writing tutorials consider the reader's journey. Look at the tutorials they should have already completed: if the functionality of a particular Code Block has already been fully explained you don't need to repeat that work; simply provide a brief one-sentence summary of its functionality and a link to the tutorial in which it is fully explored.
Each Code Block should be independently functional. Ideally, each code block could be compiled and executed at the end of each Step; if this is the case then feel free to make a note of this at the end of each Step and encourage the reader to test the program out and watch how it changes from Step to Step. Where a concept being introduced is too complex, however, simply split it into logical chunks and note that the program will not function until Step N is complete.
When excluding existing code from a following Code Block bracket it on the lines above and below with three period characters in square brackets:
[...]
Code Block
[...]When using these to indicate missing code for the first time in a tutorial use a NOTE type callout to highlight their meaning:
> **NOTE:**
> ``[...]`` in a Code Block indicates existing code which has been excluded for the sake of brevity. There is no need to type ``[...]`` into your program.This will render as:
NOTE: Seeing
[...]in a Code Block indicates existing code which has been excluded for the sake of brevity. There is no need to type[...]into your program.
For questions of grammar consult the Chicago Manual of Style. Other best practices as they relate specifically to Enlightenment Documentation can be found below.
The Documentation Guide itself serves as its own best-practice sample; edit this page to see the raw Markdown if further reference is required.