Skip to content

Intro: reorder topics in lesson description #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mmesiti wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Intro: reorder topics in lesson description #341

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions content/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ This demonstration will be mostly **independent of programming languages**
using the [CodeRefinery conda environment](https://coderefinery.github.io/installation/conda/)).


We will discuss best practices, and briefly discuss the available tools.

Then we will discuss the form of documentation which is the most immediate to write:
We will start by discussing the form of documentation
which is the most immediate to write:
**in-code** comments, and docstrings.

We will step up our game and discuss **what makes a good README**. For many
To step up our game we will discuss **what makes a good README**. For many
projects, a curated README is enough.

We will then learn how to build documentation with the
Expand All @@ -23,6 +23,14 @@ The approach that we will learn will be transferable to
[GitLab Pages](https://about.gitlab.com/features/pages/) and
[Bitbucket Pages](https://pages.bitbucket.io).

After we have seen Sphinx as an example,
we will see a brief taxonomy of the other popular tools and solutions,
and finally, once we know what tooling can do and how to use it,
we will take a step back and look at best practices:
what makes documentation important and useful and how to best maintain it.



```{prereq}
1. Basic understanding of Git.

Expand Down
Loading