REC1: Documentation - Challenge

[rgaiacs]

I don't think that "create a simple page of documentation for your software using the GitHub page" is a great exercise. R has a different way to write documentation. I think that is more important ask people to write a minimal README-like documentation. I would replace this exercise with something like

For the Python or R script provided below, write a minimalist documentation that includes the best practices mentioned before. After write your documentation, swap it with your neighbour and provide feedback to each other.

Python Script

import pandas

def __main__():
    csv = pandas.read_csv()
    csv.plot()

R Script

library(ggplot2)
csv <- read.csv()
ggplot(csv, aes(x=x, y=y)) + geom_point()

Notes about the scripts

The scripts should have 12 lines or less. It should depend of a popular third-party library. It should read a CSV file. It should create a data visualisation.

[orchid00]

hi! @rgaiacs @fpsom @mkuzak @allegravia @tobyhodges I would support that github pages is not the best for this challenge about documentation. Although I think documenting code is some other point too. I would suggest people to populate the README file with the suggested points here: https://guides.github.com/features/wikis/ This links says: "Two common ways to document a project are README files and wikis:" I think if they fill the README suggested points is good enough for the challenge and letting people know about the wiki feature of github is a plus, but wouldn't go on creating a wiki for this episode.

What do you guys think?

Documentation is a topic that all of the episodes are pointing to, so would be good if we all agree on what documentation entitles.