Helping users

Most of these tips help both the end user directly while browsing the manuals, but also search engines (locally and external).

Visuals: pictures & videos

Starting an advanced tutorial with a relevant picture comes highly recommended. Having a wall of text and scary warnings scares away potential interested researchers whom we point to these tutorials to help them solve their research problem. You can embed videos showing results or quickly demo how to set up things. We also encourage making short videos (say 1 to 5 minutes) demonstrating nice features. We can upload these videos on our YouTube channel and list them on our video page.

Titles and subtitles

Put the fundamental keywords as early as possible in a title.

For tutorials, use method keywords as early as possible, and avoid mentioning specific systems. Keep the titles short so that they preferably only span one line in the left-hand menu.

Examples:

Before

After

Analysis of the VCD spectrum of Oxirane with VCDtools

VCD: Vibrational Circular Dichroism

TDDFT Study of 3 different Dihydroxyanthraquinones

TDDFT, TDDFTB, TDDFT+TB, sTDDFT

TlH (thallium hydride) Spin-Orbit Coupling

Spin-Orbit Coupling with ADF

NiO and DFT+U

DFT + Hubbard U

Au-(4,4’-bipyridine)-Au molecular junction

NEGF: Create a Molecular Junction

Keywords

Here we mean Keywords as in the words people use to search. In our context, this is typically a specific property, application, calculation type, or xc functional.

The most relevant name of such a keyword should ideally be in the url, and in the ‘h1’. This can be achieved in Sphinx by using the keyword both in the toc (url) and on the title part of the .rst (h1). Keywords and their synonyms should also appear naturally in subsection headers (‘h2’, ‘h3’) and in the text.

Before writing documentation, do a quick search on Google, including Google Scholar or the relevant scientific journals to see which are the most common used keywords for a particular feature or application. What you as a developer think is a logical name, may not be so to the end user. The user should find the relevant part of the documentation by using the keywords they use themselves, which usually is common in the field. Also it helps the user if we also think about the application rather than the keyword (e.g. for T-NEMD consider to include thermal transport as high-level as possible). Use both EPR and ESR, XANES and NEXAFS, IR and Infrared spectrum; TDDFT, excitations, absorption, UV/VIS, …. You can also use alternative names in the Index.

Cross-linking

For the end user it is helpful to have more relevant cross-links. E.g. from the UV/VIS manual part in ADF to the two tutorials on that, and vice versa. And include a link to POLTDDFT as a fast method for UV/VIS spectra.

It also helpful to cross-link across manuals with the same properties. E.g. a person lands on NMR in the BAND manual by a (local or Google) search and he does not figure out how to do that for molecules and the BAND manual search will not give that at the moment, either.

More ideas for helping users

A link to support could also be useful, as well as better site-wide search and inter/intra-doc search options. Note that this document tries to show some ideas to make it easier users who are looking for “helping users” by having it in the url, the h1 and an h2.