Creating Documentation

This page is under construction and currently incomplete

Here you can find some tipps for good documentation. This page is based largely on a FRUKDuK Workshop from Fall 2022, where the topic was discussed at length.

TL;DR

Structure your Wiki into Overview Pages and generally applicable HowTos

Constantly update your Wiki, even with small changes
Use macros and formatting to make your pages more readable and appealing
Sort your Drive by Office → Topic → Time. Do not include "random" folders".
If your drive is well-sorted, archive more rather than less.

Wiki vs. Drive

In General:

A Drive is more useful for storing information specific to a year or semester, since folders are more easily organized. Documents can also easily be made accessible to multiple people (including those not on the board).

A Wiki is best maintained and edited over a longer period of time, since generally applicable pages can be easily linked to and from.


Beispiele:

Wiki

Drive
Continuously added to over multiple board generations
(e.g. lists of people, potential sponsors or login information)		Edited by many people over a short period of time
(e.g. helper sheets, event schedules, ToDo lists for a specific instance of an event)

Searched for Topics/Keywords
(e.g. protocols, meeting summaries)

Sorted by Date
(e.g. planning documents, invoices)

long-term and generally applicable
(e.g. HowTos, board decisions)

short-term, but maybe useful in the future
(e.g. invoices, order confirmations, planning documents)

Source of truth

The Source of Truth for any given information is the authoritative source, meaning that it dictates what is correct. Consequently, it's very important that no contradicting information is created. For a wiki, this means that e.g. a set of tutorial is only in one place, which is linked to from other pages.  If something changes, only the more general article has to be edited, minimizing the potential for false information. This is also true for Drives and similar archives, so in short: Whenever possible, link or embed. Avoid copying and pasting as much as possible.

Wiki structure

To maintain a single Source of Truth, detailed information for executing specific tasks should be contained in general instructional pages ("processes" below), which can then easily be linked to. Using embed macros and tags, pages can also often be automatically amended, which saves time and avoids confusion.


Some ideas for useful summary pages and lists:

List of relevant peoplePeople in the department or the organization (good for successors)
Login informationLogin information for online shops etc.
Semester timelineListing all ToDos that repeat each year/semester in temporal order
List of potential sponsorsContact information for potential/past sponsors for events etc.
ToDo list for larger/generic eventsToDos that do no vary for each instance of the event

Protocol Archive

Protocols are a special case, since pdf files uploaded to the wiki can be fully text-searched. This is very useful if you trying to find out if a topic has been previously discussed, since you don't have to go through all the files separately. This is also possible in a Drive, but with less options to narrow the search.

Updating the Wiki

A wiki page should be as current as possible at all times. This means you should continuously make small updates, even just single sentences or corrections.

Macros

True power users use macros for specific use cases (and not just as a gimmick, like I do) to make pages easier to navigate and nicer to look at.

Just play around with some things and see what you like (Lächeln).


Here you can put an email template, more specific instructions or a list, possibly even as a

fancy panel with custom format

Data and Drive Structure

To make files in a drive or similar file system easy to find, the following structure is strongly recommended:

This way, even files whose location you do not know are easy to find. Here are some more tips:

  • Make the topic rather narrow. Make more folders rather than archive files where it doesn't really make sense.
  • No "random" folders. Stuff only gets lost in those.
  • In a well-structured drive, archive more rather than fewer files. Your successors will thank you!