Description & README

Each application has a page where the developer can present their project, host documentation and link to relevant resources. The page consist of the following elements:

  • Description (README): The core content of the page is pulled from the README markdown file, which can be edited using the application editor.
  • Developer and Application Information: Information about the developer and application versioning are pulled automatically from the system.
  • Citation: A citation can be specified in the "Citation" section of the application editor, and will be shown on the page immediately below the description. Read more here [link].
  • License: A license for the application will be shown as plain text based on the license file, which can be edited using the application editor.

README Tips and Best Practices

Markdown: The README file is rendered as Markdown so you can add headings, lists, code snippets etc. If you need a brush-up of how Markup works, this cheat sheet is pretty handy.

Be nice to your end-users: we all recognize the joy of working with well-documented tools (and the pains and frustrations of the poorly documented ones). Our experience making sure that a few basic things are covered helps your users a lot and will help your tool get found by search engines:

  • Descriptive title
  • Summary of what the tool is used for
  • Documentation covering which inputs the application takes (including any constraints); explanations of the different settings and options; and an explanation of the output the application produces.
  • Examples! Examples! Examples! An example says more than a lot of words. It is a good idea to include at least an example of a correctly formatted input and an example of a typical output.

A few examples of the type of outputs the application produces and what these mean

Feel free to use the template below as a starting point:

# Title of the application

Summary: An overview of what the tool is all about, what it is used for, and where and by whom it was developed.

## Inputs and Settings

Here, provide simple documentation, including examples, of the inputs and options that the user should provide 
including potential formatting requirements. 
Consider including examples of valid inputs to show the correct usage of the input arguments.

## Output

Here, provide a short description of the outputs that the users of your application can expect.

## FAQ

If you are aware of common questions or issues, include these as well as answers or solutions to these here.

Including images in the README file:

You can include images directly in the README markdown file. To do this, upload the image (say example.png) to the source files, and add it in markdown like this:

![My Image](example.png)