Wiki

The Serval Project Wiki (of which this page is a part) is one of the principal means for organising the project's work and making the project accessible to new users and contributors.

The following instructions and policies should be observed by all who edit the Wiki.

The Serval Project Wiki uses Dokuwiki namespaces to organise content. Namespaces affect navigation through the breadcrumb links at the top of each page, which are formed from the titles of the namespaces in which the page is enclosed. Namespaces should naturally reflect the navigation structure of the Wiki, since namespaces are used to group related pages and navigation associates topics hierarchically.

Namespaces affect developers because they are used when editing a Wiki page, as the address of another page when creating a link. For example, a link to this page is written in Wiki syntax as [[:content:dev:wiki]].

  • Use short, consistent and logical namespace names
  • Use short, consistent and logical page names but not as short as namespace names
  • Use names that make sense within the scope of their namespace, eg :content:tech:roadmap is better than :content:tech:tech_roadmap
  • Every namespace (except :content) should have a main page called main_page which links to all or most pages within the namespace
  • Use short, descriptive titles on namespace main pages, which make sense when chained together in breadcrumb navigation
  • Link to namespace main pages using a colon suffix, eg, [[:content:dev:]] instead of [[:content:dev:main_page]]

Namespace structure

The Serval Project Wiki uses the following namespaces:

All other namespaces are deprecated (ie, should only contain Dokuwiki REDIRECT pages). In particular:

A Wiki is a whole bunch of links, resources and how-to information, some internal and some external. Dokuwiki reveals which are external (eg, Serval Project vs Serval Project), so there is no need to collect all the external ones together as though the external-ness of a link were its most important characteristic.

When navigating a Wiki, one usually has a goal in mind, like looking for information to solve an immediate, specific problem. Suppose for a moment you cannot work out how to use Git to submit a patch. You come across a page with the following links:

  • Development
  • Links and Resources

Which one do you follow? The problem is that the whole wiki is “how-to, links and resources”, so having a page (any page) with that title is a tautology, and frustrates navigation. The (mostly) external links that are typically collected into “links and resources” or “external links” pages ought to be distributed within the whole structure of the wiki, which in turn ought to be organised and navigable according to topics of interest.

The existence of a “links” page is usually an indicator that the information architecture of the Wiki is inadequate. Whoever added the page probably could not figure out where to put a link, and created the catch-all page instead of solving the underlying problem.

Dokuwiki

This section relates directly to using Dokuwiki. Even if you have used another Wiki before, it is worth familiarising yourself with the variations of this particular Wiki.

  • Playground - practice your skills
  • Dokuwiki - how to use your Wiki
  • Syntax - how to edit Wiki pages
  • Users - before creating a User page, please read

Login