Free Software Directory:Website guidelines
Sections in a page should start from second-level heading
This means using
== Example == as next heading level if the parent is supposed to be the page itself. See https://www.mediawiki.org/wiki/Help:Formatting#Text_formatting_markup for more recommendations.
Avoid CSS styles and use CSS classes
This is recommended to ease readability and maintainability.
Scripts must be implemented only as optional dependencies, since the HTML5 standard itself states that web browsers that do not support scripting, or that have scripting disabled, might be unable to fully convey the page author's intent. On top of that, the user is unable to attest that the same script that was once trusted is the same that is being run.
…keeping in mind that text-only web browser lack the physical means to represent CSS, complex layouts and so on…
There are however some edge cases that still need research, or need some compromises (whether for or against JS):
- Deal with Template:IRC text countdown.
- Find a way to display "pending entry under review" warning without JS, while still implementing similar conditional checks (with Mediawiki Parser Functions perhaps?).
- Decide if Property:Prerequisite description and Property:Component programs will use one of Page Forms' combobox / tokens or if they will be non-autocompletable properties of Page type, or if they will be a dropdown (the last one is risky for 16000 entries of the FSD).
- Decide if form fields that use datepicker should be converted to date.
- If form fields ever have the "uploadable" in their declaration, decide if they should be kept or if upload should be done by request.
- Decide whether to use the "editor" parameter for form textareas.
Avoid displaying Semantic MediaWiki queries
This is because they use more resources. An alternative is to set
|searchlabel set to a phrase describing the purpose of the query. This has the advantage that Semantic MediaWiki will pass less time processing the query in case where some subject changes their fields of interest.
If you are looking for a way to only show pages describing subjects which belong to a certain group and don't want to get additional information, a possibility would be to use categories instead of Semantic MediaWiki queries since categories themselves can display all their member pages. However, categories do have the caveat that their subpages don't get moved when the parent is.
Tabular HTML layout isn't generally a good idea for accessibility, be it for screen readers, text terminals, or magnified screens. They are good to represent raw, statistical, or comparison data. If you must use tables, this section describes caveats to take into account.
Avoid tables that make the page width exceed 71 characters
This also includes spaces and non-text areas.
A good way to test this is to use some terminal emulator such as GNOME Terminal with its width set to 80x24 (default) and use a browser such as Lynx. If this number is exceed, Lynx should render the table columns separated by one space, which makes the table confusing to read.
This issue is specially important because one cannot simply recommend everyone to increase their terminal's text width, either because they don't have bigger displays or because they make use of some screen magnifier (in which case they have to keep the terminal fit in the magnifier in order to read it without change the focus back and forth).
Note that the text inside the tables also counts towards the width count, so a long paragraph can easily make the page exceed the limit.
Avoid lists inside table cells
In text browsers which respect the terminal's text width (e.g.: Lynx), the lists are always rendered in the start of the next line, and the table column headers are always separated by a single space. In both changes this makes it difficult to understand where the new cell or heading start.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the page “GNU Free Documentation License”.
The copyright and license notices on this page only apply to the text on this page. Any software or copyright-licenses or other similar notices described in this text has its own copyright notice and license, which can usually be found in the distribution or license text itself.