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       | VCD: Vibrational Circular Dichroism                |
| VCDtools                                           |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| 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                  |
+----------------------------------------------------+----------------------------------------------------+


Link to download files
======================

**WRONG**: To download the structure, click "here"

**RIGHT**: "Download the structure", or Download "the structure", or
Download "file.txt".


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.
