First episode needs more discussion and restructuring

[allegravia]

The structure of this episode is currently confusing. Here are the potential changes that we (Mateusz and Allegra) discussed in Genoa (the suggested section headers mentioned in the following are just meant to give an idea of the corresponding content):

1) The first part of the "Hosting a project on GitHub" section (text until - and including - the bulleted point list) is not about GitHub and should be part of an initial "What are the benefits of making your software project public from the beginning?" section. 2) This (new) first section should be followed by a second section "How do I make my project publicly accessible?". This section should have the following sub-sections:

• "Use a version control system to keep track of changes in your code"; the discussion about "How does version control help your research", could be moved to this section

• "Hosting a project on GitHub", in which the part about GitHub would benefit from a bit of expansion.

• "Documenting your code". This section should have the following sub-sections:

  1. "Write a good README - The 'front page' of your project". I suggest that we refer to README text files that should be always associated to a coding project (not only on GitHub) with description of the project, instructions for installation and usage, and examples. Then I would talk about the README.md file on GitHub. We could also provide links to guidelines on how to write nice README files (for example this or this, to a template to make a good README.md file and to good examples (see this list for example, and this example in particular).
  2. "Documentation"; The Discussion at the beginning of this section ("What experiences have you had with good or bad documentation") should be changed into the following one: Think about software that you wanted to install and use in your work. Think from the user perspective: was it easy to download it? Was it easy to install it? What kind of documentation was provided? There was any info you would have liked to find associated with the software (but you didn't)? The developer perspective is not relevant for this discussion. In order to reflect from the developer perspective, we can introduce a Challenge: Have you ever written documentation for your own software? If yes, what type? How? Where? If not, why? Mateusz will provide the link for the last Challenge of this episode.

• "Make your software (re)usable" When discussing the importance of good code, we should stress the importance of commenting the code (to make it more easily readable by collaborators and therefore more accessible)

• "Publishing" This section needs expansion.

---

Here is how I see the structure (to be discussed) of this episode:

A) "What are the benefits of making your software project public from the beginning?"

B) "How do I make my project publicly accessible?".

• "Use a version control system to keep track of changes in your code";
• "Hosting a project on GitHub"
• "Documenting your code".
  • "Write a good README - The 'front page' of your project"
  • "Documentation"
• "Make your software (re)usable"
• "Publishing"

[orchid00]

maybe @mkuzak can verify if this issue is now addressed.