Documentation

Documentation is extremely important. Here is our short list of recommendations:

• Document from the start and use "future you" as a reference: imagine the information needed to understand a piece of code.
• Write "speaking" code, use long variable and function names, and follow software design patterns - it saves 80% of documentation.
• Use a documentation framework that suits your programming language, (a) with a version support and (b) that allows external contributions.
  • Plain text files within the code
  • R: Markdown vignettes
  • Python: reStructuredText
  • Top ten reasons GitHub is a great tool for creative writers
  • Read the Docs
  • GitHub pages
  • Wiki hosting services on Wikipedia

Guide: What license should I use for Documentation

You should not use a software/code license for text and images. These are licenses suitable for documentation:

• Any of the Creative Commons licenses. Depending on your goals, chose one!
• GNU Free Documentation License (discussed on Wikipedia)
  • See also the lists of free and nonfree documentation licenses at GNU.

This is an opinionated view. What is your experience? Get in touch and contribute!