the repository post, Gabriel Devenyi and Greg Wilson wrote some
suggestions for how the new lessons repositories should look like
post about metadata
post about overall file structure). From my experience at the
Mozilla Science Lab sprint I don't like Gabriel's
metadata because I don't believe it helps very much. I also don't
like Greg's proposal to duplicate some files in every Git
repository, so here are some changes that I suggest.
In addition to Greg's design choices:
- Only automate the actions that users and developers will need to do very often. We try to automate workshops' home page but we are going to revert it. For that reason I think we should wait until people complain about the lack of some script before we write it.
The lesson repositories must have two branches:
master branch will store
the lessons in Markdown (or any other format, that can be convert to
HTML, wanted by the community). The
will store the HTML version of the lesson so that students can view
We had exactly this approach until a few weeks ago
bc repo. Why go back? In
bc, we only
gh-pages a few times and
I would like to suggest that the topic manintainers do it before
days proposed at last month meeting.
Also, this approach will avoid the problem of have Markdown and HTML side-by-side since Markdown extensions support by Pandoc aren't supported by Jekyll.
Overall Layout for the Master Branch
Changes to Greg's layout:
glossary.mdin favor of linking words to Wikipedia articles.
_includesto avoid duplication of files across repositories.
Makefilewill download the needed files from a "third-party" server when needed.
bin/to avoid duplication of files across repositories and scripts that no one will use. In case we need some tool for managing lessons it should live in its own repository and we should ask contributors to install it.
Software and Data
I suggest dropping
data/index.md to avoid the work of keep them
updated. Contributors can find the "description" of the
$ grep 'filename.ext' *.md
Changes to Greg's proposal:
make topic dd-slugbecause is easy to copy one of the previous topics and correct the filenames if needed.
make checkshould run
swc-lesson-check(that needs to be installed).
make siteshould download the necessary files (e.g.
_includes) and after that build the lesson website locally for previewing.
make releaseshould update
master. This should be only used by topic maintainers.
Dialogue & Discussion
You can review our commenting policy here.