Writing a Field Guide with Other People
A field guide is usually written by more than one person. One author takes the sedimentology, another the structure, a third puts the trip together. Left to itself that means emailing folders around and hoping nobody overwrites anybody, which works until the day it does not.
VRGS can instead share a project's guides through a GitHub repository. Every author works in VRGS as they always have. Two commands move work between them, and VRGS keeps the history of who changed what.
There is no need to know anything about git to use this. There are two commands, and neither of them can lose your work.
What you need first
- A private GitHub repository for the guides, created by whoever is organising the trip. It can be empty.
- A GitHub account for each author, with access to that repository.
- The VRGS GitHub app installed on that repository by a GitHub organisation owner. This is done once, and it is what lets VRGS reach the guides and nothing else in your organisation.
All the guides in one VRGS project are shared together, because the repository
covers the project's whole HTML folder. You cannot share one guide from a
project and hold another back.
Signing in
Right-click any field guide in the Collections tree and choose Sign In to GitHub….
VRGS shows a short code, copies it to the clipboard, and opens the GitHub page that asks for it. Paste the code, approve the request, and go back to VRGS. The sign-in finishes on its own.
You do this once per computer. VRGS keeps the sign-in in Windows Credential Manager, the same place Windows keeps your other saved sign-ins, and renews it quietly when it expires. You never type a GitHub password into VRGS.
The guide folder's right-click menu shows who is signed in, so if work is being recorded against the wrong name that is where to look.
Setting the guides up, once
The first author to share does this. Right-click a guide and choose Share These Guides on GitHub…, then paste the repository address. VRGS records everything already in the folder and sends it.
Everyone else then gets the guides by pointing their own VRGS at the same address, again with Share These Guides on GitHub…. Their copy is brought up to date with what is already there.
Videos are deliberately not shared. GitHub refuses any single file over 100 MB, and a repository keeps every version of a film for ever, so a few replaced recordings would make the guides slow to fetch and impossible to trim down again. Keep video on your shared drive and photographs in the guide.
The two commands you will actually use
Once sharing is set up, the guide folder's right-click menu has two commands.
Get Latest Changes
Collects everyone else's work and brings it into your copy. Run it before you start writing for the day.
If you have edits you have not shared yet, this stops and says so rather than merging on top of them. Share yours first, then run it again.
Share My Changes
Records what you have written, collects anything that arrived while you were working, combines the two, and sends the result. Run it when you have finished a page, and again at the end of the day.
Both commands show progress in the Messages panel, with a cancel button, and both run in the background so you can carry on working while they finish.
What happens when two people edit the same page
This is the part worth understanding, because it is the only thing that ever needs a decision from you.
Different paragraphs of the same page combine automatically. If you reword an introduction while a colleague corrects a dip reading further down, both edits survive and neither of you is asked anything. VRGS writes guide pages so that this works.
The same paragraph cannot be combined, because there is no way to know which wording is meant. When that happens VRGS stops and changes nothing. Your work stays exactly as you left it, it is already recorded safely in your copy, and the message tells you to speak to whoever else edited that page. Agree between you which version is right, put it in, and share again.
VRGS never leaves half-merged text in a page. Some tools mark the disputed lines inside the file and leave you to sort it out; that would corrupt a guide page, so VRGS refuses the merge instead.
Working so that this hardly ever comes up
Conflicts are rare if the work is divided so two people are seldom on one page at the same time. The arrangement that suits most trips is one author per day of the trip, since the guide template already lays pages out that way. Everyone can still read and fix anything; the point is only that routine writing happens in different places.
The one file everybody shares whatever you do is the guide's navigation — the running order in the Guide sidebar. Changes to it combine like anything else, but it is worth telling each other before reorganising a whole guide.
After changes come in
Guide pages you already have open in the editor are not reloaded automatically. If Get Latest Changes brought something in, close the page and open it again to see it.
What is kept, and what is not
| Kept in the shared history | Not shared |
|---|---|
| Guide pages | Video |
| Photographs and figures | Previous-version backups VRGS keeps beside each page |
| The guide's navigation and menus | Anything still being written when VRGS was interrupted |
| The guide stylesheet |
Everything that is kept is kept for ever, with the name of whoever changed it. That is the point of sharing this way, and it is also why a private repository matters: anything committed once can be read back later, even if it is deleted afterwards.
If something goes wrong
| What you see | What it means |
|---|---|
| "There are unsaved changes here" | You have edits that have not been shared. Share yours, then collect again. |
| "Somebody else shared their work while you were writing yours" | Ordinary. Run Share My Changes again; it collects theirs first. |
| "Somebody else changed the same part of a page that you did" | Nothing was changed. Agree the wording with them, then share again. |
| "GitHub did not accept the sign-in" | Sign in again from the guide's right-click menu. |
| "GitHub could not be reached" | The connection, not the guides. Your work is saved and can be shared later. |
Nothing in this list means work has been lost. Every one of these stops before changing anything, and your own writing is always recorded in your copy first.
See also
- Virtual Field Guide Editor — writing the guides themselves.
- Building and Delivering a Virtual Field Trip — how a guide fits with flight paths, media and a live session.
- Multiuser Virtual Field Trips — running a live trip through a guide.