Versioning and URLs

User types

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 an 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 book 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 referenced by other people. Don’t be afraid, git makes it very easy to make this possible. Git allows you to go back in the git history. To make this as easy as possible for readers, you can assign versions using TeachBooks versioning instead of having the readers scroll through a long list of (not alway very descriptive) commit descriptions.

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!

If you are part of the previous group, but at some point decide to make a new version of the book while keeping the old one, you could do so without dealing with version numbers and changelogs. Just publish both versions online.

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 flexibility, 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 in order of increasingly effort and impact. You can combine use-cases to your liking:

Use-case	Publish versions on separate URLs	Use TeachBooks versioning with a changelog	Publish your book with a publisher
Book changes over time, but you don’t want to deal with versioning
Occasionally releasing a new version while keeping the previous version, with minimal effort for versioning	Recommended
Continuously adding content and solutions or updating crucial mistakes		Recommended
Allow referencing specific versions	Can be considered	Recommended
Taylor-made book per academic year	Recommended	Recommended in case of students retaking a course
Increase findability or benefit from publisher’s brand			Recommended

Read more about each of these measures on the following sub-pages.