Documentation

Your project documentation will inevitably be the most important part of your project going forward. It’s important to use any and all means at your disposal to document your code.

Include a lot of usage examples and keep it concise and clearly structured.

There’s even entire development strategies with their starting points in the project documentation. The simplest and most attrative of them is README Driven Development.

Dedicated documentation

This is likely the main entry point for new users. The dedicated documentation should first and foremost provide a higher level description of the software. It’s important to give a gentle introduction but still get to the point the point quickly.

It should be available online, either as part a README file for small projects or more likely a full web site. Liberally include code examples and if possible a short demo tutorial where the user can follow along.

Inline documentation

Worry more about not documenting enough than documenting too much.

Always document classes, methods, and functions. It should be clear what input arguments are expected and what output it is transformed into. A function documentation should also describe under which condition it raises exceptions.

A welcome addition is to provide consice usage examples along with the e.g. function documentations.

@curry
def grep(pattern, line):
  """Match a simple pattern substring in a given string.

  Note that the function would also work to check for an item in a list,
  a key in a dictionary etc.

  Args:
    pattern (str): substring to match with
    line (str): string to match against

  Returns:
    bool: if ``pattern`` was a substring in ``string``

  Examples:

  .. code-block:: python

    >>> directors = ['Quentin Tarantino', 'PT Anderson']
    >>> list(filter(grep('Anderson'), directors))
    ['PT Anderson']
  """
  return pattern in line

Find out how to document functions in your language and stick to accepted conventions.

Flowcharts

Flowcharts can convey overview in ways that is impossible to put into words. It can be a great way to organize e.g. a pipeline of functions that will help you in the design of your project.

A great, dedicated flow chart creation tool is Delineato, $6.99 on the Mac App Store. Another option that works surprisingly well is Apple Keynote making use of the Insert > Line > [Straight] Connection Line.