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.

Avoid CSS styles and use CSS classes

This is recommended to ease readability and maintainability.

Avoid JavaScript, directly or indirectly

This must be avoided, since the HTML standard itself states that a document provider can't expect the user-agent to support client-side scripting. 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.

As a general recommendation, testing by doing contributions or viewing the FSD with text browsers such as Lynx, Emacs Web Wowser (EWW), or other JavaScript-disabled front-ends should not give you any issues.

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 |limit=0 with |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.

Tables

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.