Good documentation practices

Jana Lasser

TU Graz & CSH Vienna

2021-12-16

Why should we document?

As researchers, we build on the work of (generations) of other researchers.

Polished publications are often not enough to build on (or reproduce) existing work.

Documentation helps us to remember what we did in the past.

Documenting our work helps to find mistakes and unclear parts (slow science).

How and what should we document?

  • Files with documentation should reside as close to the primary research (data, figures, code, ...) as possible. Good practice: README file in the same folder.
  • Get the metadata right: Who did the work? When (if relevant: where)? How are you reachable in case of questions (email address)? Are there related documents (link them)? If there are multiple versions of this document, include version information.
  • Describe what you did in clear language. No need to sound overly sophisticated. Describe the file structure of the repository/folder/collection and what to find where.
  • Use structuring elements (headlines, tables, bullets) and enrich with links.
  • Don't use proprietary or program specific file formats (.docx!). Good practice: use Markdown (.md). Alternatives: plain text (.txt), Open Document Format (.odt).

    • Markdown

    Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

    Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.*

    *Borrowed from https://daringfireball.net/projects/markdown/

    Markdown example

    HowTo: Markdown*

    Element Syntax
    heading # (H1), ## (H2), ### (H3), ...
    bold & italic **bold text**, *italic text*
    ordered list 1. First item
    2. Second item
    table | col 1 | col 2 |
    | --- | --- |
    | text | text |
    link [link text](link url)
    image ![alt text](path to image)
    horizontal rule ---

    *See also Markdown cheatsheet https://www.markdownguide.org/cheat-sheet/

    Where can you use Markdown?

  • GitHub renders markdown files automatically. Best practice is to have a README.md file in the repository's root directory (example).
  • OSF features Wiki pages that can be formatted in markdown (example).
  • A number of "pad" implementations use Markdown to structure and render their text, for example HackMD and torchpad (example).
  • Other examples?

    • Exercise [20 min]

    Document your research! [either OSF or GitHub*]

    Pick one of your (ongoing or finished) research projects. Create an account on OSF and make a new project for your research there. Document your research using the Wiki function of OSF and following documentation best practices. If you want to, you can also upload other documents or data and describe them.

    Pick one of your (ongoing or finished) coding projects. Create a local and remote Git repository for it and push your code there. Document your research in the README.md file, following documentation best practices.

    *Note: if you don't set your project/repository to "public", it will remain invisible to anybody but you.

    Feedback [15 min]

    Show your team-members your documentation (share your screen if you don't want to invite them to your project/repository).

    Take 5 minutes / team member to answer the following questions together:

  • Is the metadata complete?
  • Was the description of the file structure understandable?
  • Are there improvements regarding the use of formatting elements you could suggest?