mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-13 14:55:51 +00:00
32 lines
2.9 KiB
Markdown
32 lines
2.9 KiB
Markdown
# Versioning and URLs
|
|
|
|
> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
|
|
|
```{admonition} User types
|
|
:class: tip
|
|
This page is useful for user type 4-5.
|
|
```
|
|
|
|
Online books can be easily updated, however, this might confuse readers. Therefore, it's good practice to be aware of this and, where needed, provide explicit version to the readers.
|
|
|
|
For example when making taylor-made books for specific academic years, you want students to be able to find their own book (even after the academic year is over). For students which take the course twice, you might want to provide some sort of changelog of what has been changed.
|
|
|
|
Another example could be a course in which you add content and solutions during the course or you're fixing mistakes which may have misinformed the reader. If this is not directly visible in the table of contents, students might not be aware of these changes. Again, a changelog could be useful to inform the reader about the change. Furthermore, a smart versioning system might tell the reader something about the impact of the addition differentiating errata and additions.
|
|
|
|
You could also think of your published book which is references by other people. As content (and the location of this in your book) might change over time, other people can use versions to refer to a fixed version in time of your book.
|
|
|
|
Maybe this all sounds confusing and difficult. No worries! A use-case could be a book which progresses in time, but in which you don't want to deal with the additional hassle of versioning. Your book could be perfectly fine without any measures on this topic!
|
|
|
|
Finally, you might consider publishing your book at an online publisher. This could increase findability of your book and you might benefit from the brand of the publisher, but it may have versioning, copyright and licensing consequences.
|
|
|
|
So, there's a few use-cases for which different (combinations) of solutions exist. These are summarized in the table below. You can combine use-cases to your liking:
|
|
|
|
| Use-case | [Publish version on separate URLs](./versios_URLs.md) | [Use TeachBooks versioning with a changelog](versioning_changelog) | [Keep old versions online](./versioning_archived.md) | [Keep source code of old versions online](./versioning_archived.md) | [Publish your book officially](./publisher.md) |
|
|
|:---:|:---:|:---:|:---:|:---:|:---:|
|
|
| Book changes over time, but you don't want to deal with versioning | | | | | |
|
|
| Taylor-made book per academic year | Recommended | | Recommended | Can be considered | |
|
|
| Continuously adding content and solutions or updating crucial mistakes | | Recommended | | | |
|
|
| Allow referencing specific versions | Can be considered | Recommended | Can be considered | Recommended | |
|
|
| Increase findability or benefit from publisher's brand | | | | | Recommended |
|
|
|
|
Read more about each of these measures on the following sub-pages
|