User stories

These stories describe how different people might want to use BibServer – the software that makes nice searchable displays of bibliographic collections. Our BibServer is only one example of a BibServer – a group or department could take the BibServer software and run their own BibServer if they want to. More info on BibServer is available on the BibServer page.

## Jim and Bibtex

Jim is an academic in the department of Maths and Stats at University of California Berkeley. He has quite a few publications, and he would like to be able to display his publications in a way that enables viewers to quickly and easily see key details about his work – such as when published, who he published with, and so on.

Jim likes to use Latex when he is authoring, so he is happy using Bibtex. In fact, Jim already has a list of all his publications in a bibtex file, and he is happy with this method of maintaining his collection. Additionally, Jim is able to put that file online, because he has access to a computer in his department where files that are put there can appear online at a web address.

This is an ideal scenario for using BibServer; in fact, it is exactly what the original version of BibServer was built for – Jim was the creator! But he has already found many people in a similar situation, and they too can easily use BibServer in the same manner with very little technical expertise.

All Jim has to do to make use of BibServer is provide the web address where his bibtex file can be accessed to the admin / upload section of a BibServer instance (for example, our instance, or an instance that his own department hosts, if they have one). Once he has done this, BibServer will copy the content of his file and build his display page for him. Jim can also use the BibServer admin to schedule regular checks for new content in his online file, or he can tell the BibServer system there is new content to get.

Alternatively, if Jim cannot get his bibtex file online, he can just upload it via the BibServer admin. If he does this, BibServer cannot automatically check for new updates, but Jim can still upload a new copy any time he wants.

Once Jim has uploaded his content, he will get back a web address where he can view and search his collection. The web address will depend on which BibServer he uploaded his content to, but it is a normal web address that he can give to anyone else for them to also access and search his collection. Nice!

## Jim’s department

Although Jim is happy now that he can have a nice searchable display of his own publications via his bibtex file and BibServer, Jim is also part of a community of other publishers – his department. The managers at his department would love to be able to easily show all the research output (e.g. publications) of all their staff members, but maintaining this is difficult – people come and go, they are independent and publish separately or with other groups, and they may not talk to each other enough! The department can easily solve this using BibServer.

At this point, the department might choose to install their own BibServer that their members can use. Let’s assume anyway that Jim is in a department that has access to some BibServer. Just as Jim was able to provide his publications via a Bibtex file, so too can his colleagues; then, their department administrator can create a collection for the whole group – all it takes is that the relevant records or collections be identified as also being part of the departmental collection.

You see, all the records in the individual collection files are stored in one big collection – which we call the BibSoup; then, the records are tagged with a collection name, such as “jim_collection”. But, records can be tagged with more than one collection. By tagging the records from staff member collections with the departmental collection tag, they can be made available in the departmental collection.

Now, there will also be a web address for the departmental collection view; individuals like Jim can still share their personal collections, but now his department can also show their aggregate output!

## Jim and sources besides bibtex

Jim likes to use a social bookmarking tool to keep lists of web pages he finds useful. For example, he searches the internet for published articles on a particular topic, say for some research he is doing for a new paper of his own, or perhaps to build up a reference collection for a course he is teaching.

Well, just like Jim did with his bibtex file, he can do the same with his Delicious lists – he just has to put the web address of the list into the BibServer admin and he gets another collection.

BibServer also supports other sources from which Jim could build such collections:

* Comma Separated Value lists
* BibJSON files
* Google spreadsheets

And new connectors can be built too! It takes a bit more technical skill as it requires doing some programming, but if you or your department are capable, there is no limit to where you could source data for your collections.

## Jim and Ryan using a custom source connector

Here is an example of a custom connector building a BibServer collection; at Jim’s department they use an LDAP server (it does not matter if you do not know what this is – it is just a system they use; your department probably has a similar system). The administrators at Jim’s department have various access rights and permissions, and they are able to list publication information to records about particular past and present staff members. The techie at Jim’s department is Ryan – and Jim and Ryan have succeeded in writing a simple script that reads this data from their server and publishes it to a BibJSON file. After achieving this, all Jim and Ryan have to do is the familiar step of registering the web address of that file (or uploading it) to the BibServer admin. Again BibServer can be kept up to date by keeping track of that file.

The great thing about this is that nobody has to worry about the permissions or authorities or changing work practices – however the staff did it before, they just keep doing it the same; the script automatically aggregates new data, and BibServer does the rest.

## Jim collaborating with Mark to write a new paper

Bibliographic collections are not just used for showing what someone has published – they might also be used as references in another publication. When Jim collaborates with other people from a different group in writing a new paper together, they find that they need a way to collaboratively maintain the list of relevant references – and of course, BibServer can do this. They can work as a group on a bibtex file or other source such as Delicious or a Google spreadsheet, or they can build a collection directly in BibServer.

But that is not all – once Mark and Jim and co. have built their relevant reference collection in BibServer, they can also use that information directly in the process of publishing their article online! By using the open scholarship publishing tool, they can refer to items in their collection by giving them keys then embedding the keys in their HTML document following the principles of Scholarly HTML. In addition to this, anyone reading their published paper will be able to browse the references in the paper via BibServer!

## Jim or Mark browsing and exporting bibliographic data

Once finished writing their paper, Jim, Mark, or others might want to browse their reference collection and export data. BibServer offers data export in a variety of formats such as bibtex and BibJSON. Also, just like the source connectors, it is possible to write exporters if you have the capabilities, so Jim or Mark could export to any format they desire.

## Peter searching for bibliographic records directly in BibServer

As an instance of BibServer fills up with records from various collections, it represents a significant volume of valuable material – and it is all openly available and searchable by others. So, when Peter wants to create a new collection, he might not even bother with importing from a file or other source – instead, he could just browse a particular BibServer and make a new collection out of the contents. This would be an easy way for him to build a collection for a new research group within his department, if his department is already using a BibServer instance, for example.

## Richard installing a new BibServer and populating it with records

A BibServer instance is a big collection of records that are all part of other collections uploaded by the people that use that particular BibServer. But now let’s say that Richard has heard of all the great stuff that Jim, Ryan, Mark and Peter have been up to with their BibServers, and he wants in! He could use their BibServers perhaps, or he might get one installed at his own research group. Now, his new instance will be empty – but because all BibServers have a common data format (BibJSON) it is easy for him to extract records from other BibServers and include them in his own instance. We refer to this murky underlying ocean of BibServer data as the BibSoup – and we are hoping to maintain our own BibServer to as large a size as possible…