Every commit in the origin/master branch is built.
If you prefer the web editor, know that each time the master branch is committed, the book is generated. While we are in draft, it is recommended to use a separate branch to do the writing. This prevents too many commits in the github repo master, as each time you save your work in the editor, a commit is done. If you use the , this is far less a problem, because you only synchronize when you made some more changes.
A reference can only be made to an article.
As far as I know, a reference can only be made to something written down in an article, i.e. a separate file. Therefore, it is a good habit to focus on exactly one thing you want to explain/write about in every file.
Referencing is done to relative locations.
If you want to refer to another article, that can be done by using a relative path. Like I have done with this link to It is probably a good habit to check that the links work, by checking the book as it is generated.
Gitbook is used to maintain Ampersand documentation in a collaborative way. This page is the work instruction for all those who help to document Ampersand in Gitbook.
to maintain documentation that changes continuously as a team, without having too much work on the coordination of this collaboration;
to get good looking documentation with little effort;
to maintain the documentation on the internet, so we can hyperlink to it from anywhere.
The documentation you are reading at this very moment is created using GitBook. It allows to write the documentation in , which is an easy to use document-format.
The documentation can be changed by the . For helping to document Ampersand, please request an authorization for Gitbook with .
The documentation is organized as a book. We prefer this over a traditional wiki, because a book contains a content part, which helps both author as well as the reader to think about structure, so everything can easily be found. Each book can be served as a (part of a) website, as well be downloaded in several forms, like pdf or e-book. We use a fully automated toolchain to build the book for each commit to the master branch of a book.
At AmpersandTarski, we currently have two repositories, each dedicated to the documentation for a specific audience:
The repository contains the contents of the book you are currently reading. You probably found it . This document is not about Ampersand, but about the way Ampersand is being developed
The repository is going to contain the documentation about Ampersand itself.
Getting started with GitBook
Getting started with GitBook
If you want to add to the documentation, it is possible to update the repository with any tool you like. However, we strongly advise to use the GitBook editor. A lot of cumbersome work is automated for you. Here are the steps to get on your way:
Once you have an account get in touch with so he can grant you access to the book(s) you want to contribute to.
You will automatically find the books at your , where you will find a button to start editing the book.
The GitBook Web Editor
The editor explains itself. At GitBook, they eat their own dogfood to write .
The GitBook desktop client
Recently, Gitbook also has a desktop client. It can be found When you install this desktop client, GitBook will make a local clone of the book. You will find it at ~home/Gitbook. As far as I know, this is not configurable, so you'll just have to deal with it. You can synchronize from within gitbook. However, if it gets a little bit complicated, I prefer sourcetree to give the correct git commands.