Table of Contents
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.
Namespaces, links and navigation
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
- 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:roadmapis better than
- Every namespace (except
:content) should have a main page called
main_pagewhich 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,
The Serval Project Wiki uses the following namespaces:
:wiki:– help for editing and managing the Wiki
:wiki:user:– contains User pages
:content– the top-level namespace that contains almost all content relating to the Serval Project. It was created when an early version of the Wiki was imported into Dokuwiki, and may one day be removed (leaving a general redirect rule in its place).
:content:dev:– material for developers
:content:tech:– Serval technology (ideas, artefacts, products) and the roadmap
:content:activity:– current and past contracts, grants and other funded or unfunded units of work
:content:devices:– information about Android devices
:content:magdaa:– the MaGDAA project
:content:meshextender:– the Mesh Extender hardware product
:content:seniordevs:– private area for senior developers
:content:servalautoshutdown:– the Serval Autoshutdown app for Android
:content:servaldna:– the Serval DNA core component
:content:servalmaps:– the Serval Maps app for Android
:content:servalmesh:– the Serval Mesh app for Android
:content:servalsam:– the Survey Acquisition Manager app for Android
:content:students:– private area for research students
All other namespaces are deprecated (ie, should only contain Dokuwiki REDIRECT pages). In particular:
:content:exercises:– DEPRECATED in favour of
:content:howtos:– DEPRECATED, see below
:content:meshhelper:– DEPRECATED, renamed to
:content:process:– DEPRECATED in favour of
:content:technologies:– DEPRECATED, replaced by
Do not create “Links” or “Resources” or “How-tos” pages
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:
- 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.
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.