General coding advice#
Coding tips#
Check this presentation from Software Carpentry for a general overview. Take a look at our own cookbook for some specific examples related to this group.
Jupyter notebooks#
For most of the interactive work we use Jupyter notebooks, see http://jupyter.org for the introduction to those.
At https://io.quantumtinkerer.tudelft.nl we have a standard computing environment where you can carry out most of your numerical work.
Software documentation#
Three key aspects to keep in mind when creating the documentation for your project:
The target audience
The content of the documentation
The structure of the documentation
The Audience#
Documentation is generally developed for two sets of target audience, i.e., end-users and developers. Having this clarity will help you to identfy the content and structure your documentation well.
End-Users: This audience is concerned with only using the software. Information about the software design, code and internal details is not relevant. Developers: This audience is concerned with contributing to the software by adding new functionality/features, tests, documentation, fixing bugs, etc. Information about the software design, code and internal details is therefore important.
The Content#
User documentation#
It should contain at least the following:
Provide a brief overview of the software answering the below questions:
What does the software do?
Who is it for?
Installation instructions
Examples and tutorials to get started
Developer documentation#
Source code documentation - docstrings and comments
Provide a contributing guide with the following information:
What to contribute? - features, bug reports, bug fixes, tests, documentation
How to contribute?
How to set up a local development environment?
Information on the branching model
Merge request guidelines
Technical reference - software design details, description of modules and components
API documentation (if applicable)
How to structure the documentation?#
As a bare minimum, user documentation should be present. A Readme file can be provided with the software that includes the following.
Brief description of the software
Installation instructions
Getting started information/How to use?(examples, tutorials)
Add the examples, tutorials, developer documentation in separate markdown files in the software repository and link them in the Reamde, thereby keeping the Readme file short.
For small projects with basic documentation, use the above approach of a Readme file + additional markdown files.
For projects with more extensive documentation, consider using a documentation hosting service such as [Read the Docs] (https://docs.readthedocs.io/en/stable/#) that offers features such as continuous documentation, notebook style documentation (embedding code in documentation), etc.