Use a real life examples. Try to use CodeRefinery and ReadTheDocs examples

use "researcher" instead. "Developer" can sound a bit intimidating or irrelevant, many researchers don't identify with the term

well-structured blog post about software documentation:
https://www.divio.com/en/blog/documentation/

A good option is using Zenodo with GitHub:
https://guides.github.com/activities/citable-code/

but maybe this fits better in the reproducibility lesson?

I saw a problem on a windows 10 computer with sphinx + RTD. The build failed on RTD.

• file reported that conf.py was utf-8, as did locale.
• When opening the file, it appeared the one character in the name in the file wasn't proper utf8 (ä or ö).
• Building the docs failed with the usual "ascii can't decode ordinal..." even though it somehow seemed to be trying to decode in utf8. I didn't spend too much time tracking it down, because...
• Changing the python interperter to "CPython 3.X" made it build successfully, but not sure

I think that most likely no action is needed on this, but something to keep in mind. I would think that if everything works normally, utf8 characters would work even with python 2.X so I'm not sure what the root problem was. Maybe mention changing to Python 3.X if things don't build.

Make sure participants understand that the Git repository can be hosted in principle anywhere.

import sphinx is not enough. Participants should also verify that sphinx-quickstart is available.

The "default" template is not available on some installations. (The particular error was not finding about.html template or some such... maybe other lines need changing).

I saw it on two computers running sphinx installed via anaconda on windows 10.

After things have shifted. Will do this once I am through with the current sweep.

Explain better what is the difference between markdown and RST and why we use both.

It appears that all coderefinery lesson pages are missing some navigation links (next, previous). This is not exclusive for the documentation lesson. The template is very similar to the Software Carpentry template, but is missing this crucial bit. This makes it cumbersome when going into a lesson chapter page (e.g. https://coderefinery.github.io/documentation/02-requirements/) because one needs to go back to the contents list to navigate to the next chapter. Unless I'm missing something!

This used to work earlier but in Uppsala this dependency was missing for most.

@Vathasav started with Snakemake as an example. This was really good and we should link to it in the material or instructor guides.

Should be on last day rather than first day

See whether we can use the example project created in
Sphinx and ReStructuredText | How do we get started on writing Sphinx documentation in RST?
in
Deploying Sphinx documentation to Read the Docs

instead of cloning a completely new project

minimum is to document how to run something (for your future self). If others will be using your code, add installation instructions, examples for getting-started, keyword reference. If many will be using it, create website, FAQ section, tutorials, etc.

Let us not show how to change "alabaster" to "default" - throws some participants off the boat without much added value. We should only mentioned that the theme can be changed and styled to heart's content.

the exercises in episode 4 (deploying sphinx documentation to read the docs) doesn't work for me with existing instructions.
However, the instructions on http://docs.readthedocs.io/en/latest/webhooks.html work. This requires the "Payload URL" on GitHub to be the URL of the integration on read the docs (and not http://readthedocs.org/build/user-doc-example) as in this lesson

People sometimes think Sphinx is related to python only, this should be better communicated.

i.e. move the exercises from here:
https://github.com/coderefinery/word-count/blob/master/doc/exercises.rst

to here:
https://github.com/coderefinery/documentation/blob/gh-pages/_episodes/04-sphinx-rtd.md

it might be confusing to have the material spread over two webpages

The default behavior is to use the same name as the repository name but this will fail for everybody except perhaps 1 person if we use the same fork name.

windows users (probably) need to use the Anaconda prompt to run sphinx commands (sphinx-build, sphinx-quickstart). Git seems to be present in the standard anaconda installation, but not nano.
TODO:

• figure out which git is available in the anaconda prompt
• figure out why conda install -c anaconda nano didn't work on a windows machine (see https://anaconda.org/anaconda/nano)

Maybe show only 1 or 2 documentation tools

The lines got added at the end of the file. We need to clarify this.

refer to https://github.com/coderefinery/git-intro/issues/129 for details

Show when and how the github pages and readthedocs should be used separately and when both.

people were struggling setting up the toc part in the index.rst (episode 04) - ideally they should not need to struggle with that because that was not the main message.

This was after pushing to the fork. It might have been a glitch/lag but we should double check.

it's very nice to repeat the forking-PR workflow from git-collab, but we don't want a majority of the time to be spent on this rather than on learning the RTD/Sphinx/RST parts

Keep the sphinx quick-start exercise, but make it optional

As in this project: https://github.com/uit-no/python-open-mike/blob/gh-pages/_config.yml

Is simpler and IMO looks better.

We mention many aspects but this one often is mentioned in passing. Documentation has to be part of the code repository. This has to be mentioned in capitals and a drawing on the white board. For me this is the one take-home message that everybody has to take from this lesson and it cannot be mentioned just in passing.

Maybe use a more fleshy example to start with, working on documentation collaboratively (instead of everyone creating empty doc from scratch). Show what can be done.

Mention with a link how to run your own sphinx server for those who do not want to deploy to RTD and not pay.

under "Good resources" in Motivation episode

• Motivation to tell why document. Lightweight
• What defines a good documentation.
• Listing tools - less important
• Deployment - some time there is not enough time for Github pages
• Teach less syntax
• Exercise - 3 - Re-use Git knowledge

just an html file isn't so exciting

In some links the URL and link text have been swapped so they link into the void.

Might be easier than copying the path.

https://github.com/new/import

The advantage would be a repository that is not forked from upstream (because the fork relation then is unnecessary) and that is built right away and does not require a change to show up at all.

e.g. http://dillinger.io/, https://stackedit.io/

Bullet points for each lesson, each episode,
Collecting experience - lessons learned.