Discussion about the content of a README file.

[MaximilienNaveau]

The following needs to be discussed below, this will be updated in function of what people think.

Template readme

A readme file should contain the following:

• the tag of the continuous integration if any.
• the title readme with dashes (needed for the html API build)
• a short description
• the copyrights
• the license
• the installation procedure
• where to find demos and the API doc

`build token` `unit test token`

Readme *or* Package Name
------

*Here a short description*

### Installation

#### Standard dependencies

*Here all the pip and apt install-able stuff*

#### Download the package

*Explain how to download the package (treep or git clone)*

#### Build the package

*Using colcon or other tools.*

### Usage

#### Demos/Examples

*Explain where to find examples (in the demos/ folder for example)*

#### API documentation

*How to build the API html doc.*
*Where to find the last built doc on the internet.*

### License and Copyrights

*update the date if it is a new package*

License BSD-3-Clause
Copyright (c) 2019, New York University and Max Planck Gesellschaft.

In the message below is the preview of the above markdown code

[MaximilienNaveau]

build token unit test token

Readme or Package Name

Here a short description

Installation

Standard dependencies

Here all the pip and apt install-able stuff

Download the package

Explain how to download the package (treep or git clone)

Build the package

Using colcon or other tools.

Usage

Demos/Examples

Explain where to find examples (in the demos/ folder for example)

API documentation

How to build the API html doc.
Where to find the last built doc on the internet.

License and Copyrights

update the date if it is a new package

License BSD-3-Clause
Copyright (c) 2019, New York University and Max Planck Gesellschaft.

[luator]

Some thoughts:

• I would suggest to merge "Copyright" into the "License" section to take less space and to move it to the bottom of the file. Most of the time users will be more interested in how to install/use/etc. so that information should come first.
• Just my personal (maybe rather non-academic) opinion but I wouldn't put authors in the README at all. It is tedious to maintain that list and it is often unclear to me after what amount of modifications a new contributor should be added there (e.g. is fixing a minor bug enough?). In the end all the information is available in the git history and GitHub also lists main contributors at the side automatically.
• I would remove the caption of the "What is it" section. The description can come directly after the main title.
• Regarding the "Readme" title: I'm not sure how much the documentation build depends on this specific wording. Would it be possible to use something more informative (e.g the package title) instead?

[MaximilienNaveau]

* I would suggest to merge "Copyright" into the "License" section to take less space and to move it to the bottom of the file.  Most of the time users will be more interested in how to install/use/etc. so that information should come first.

I agree and did the modification

[MaximilienNaveau]

* Just my personal (maybe rather non-academic) opinion but I wouldn't put authors in the README at all.  It is tedious to maintain that list and it is often unclear to me after what amount of modifications a new contributor should be added there (e.g. is fixing a minor bug enough?).  In the end all the information is available in the git history and GitHub also lists main contributors at the side automatically.

I forgot that github actually does it for us, I am in favor to remove it, (I did the modification but it can be reversed if strong opinions arise)

[MaximilienNaveau]

* I would remove the caption of the "What is it" section.  The description can come directly after the main title.

I agree and did the modification

[MaximilienNaveau]

* Regarding the "Readme" title: I'm not sure how much the documentation build depends on this specific wording. Would it be possible to use something more informative (e.g the package title) instead?

I never know what to put, the package name will be redundant but README is not the best descriptive word...
I suggest people do whatever they like with this...

In the final doc the Readme will be displayed as is in the front page, for example:
https://machines-in-motion.github.io/code_documentation/mpi_cmake_modules/docs/sphinx/html/index.html

[luator]

* Regarding the "Readme" title: I'm not sure how much the documentation build depends on this specific wording. Would it be possible to use something more informative (e.g the package title) instead?

I never know what to put, the package name will be redundant but README is not the best descriptive word...
I suggest people do whatever they like with this...

In the final doc the Readme will be displayed as is in the front page, for example:
https://machines-in-motion.github.io/code_documentation/mpi_cmake_modules/docs/sphinx/html/index.html

Oh, so there is no technical requirement for it to be "Readme"? Your comment sounded to me like the documentation build depends on this and would fail otherwise. If this is not the case, I would also say we can just let the maintainers of each package decide what makes most sense (e.g. just the package name or something a bit more descriptive).