📗 Open Ethnographer Manual

This is the manual for Open Ethnographer, our open source, custom software application for ethnographic coding. We use it on this very forum. As usual, this manual is a wiki – update and extend it as needed.


1. Introduction

2. Getting access

3. Coding with Open Ethnographer

4. Managing codes, annotations and settings

5. Using the API

6. Process for a whole coding project

7. Archiving ethnographic data

8. Contributing to development

1. Introduction

Open Ethnographer is an open source tool for Qualitative Data Analysis (QDA), which is a way to systematize and understand long chunks of text and to make sense out of it.

Usually, there are four main steps in the QDA analysis:

  1. Preliminary coding. A thorough reading of the content that leads to a draft list of codes, or tags, for certain portions of text.

  2. Coding. A careful reading, this time assigning a ‘code’ (a “kind of hashtag without a hash”) to a relevant portion of a given text.

  3. Building categories. Group codes into categories for further analysis.

  4. Analysis. The content of the categories is described with references back to the text and the original quotations.

Open Ethographer (OE) is used for coding the content of a webpage without downloading it first. It is a simple to use and intuitive tool, and the instructions are below.

There is also another, legacy version now called “Open Ethnographer for Drupal”, documented here. All relevant parts of that documentation have also been incorporated into this topic, so it is not relevant for anything anymore.

2. Getting access

To be able to use Open Ethnographer, you must be a member of the annotator Discourse user group.

To become a member of that group, visit the page of the group and click the button to apply for membership. You will be able to write a bit about why you’re applying. Then, the annotator group owners will see your request and one of them can then approve it. The owners are currently @amelia, @matthias and @alberto – if necessary, you can message them directly if you experience a problem with this process.

In addition, all administrator users of the Discourse platform automatically have access to Open Ethnographer.

3. Coding with Open Ethnographer

The basic steps are the same independent of the type of material you will be coding:

  1. Log in to edgeryders.eu as normal, with an account that is a staff user (moderator or admin).

  2. Visit section “User Settings” of the Open Ethnographer interface and create a user settings record for yourself. See section “Managing codes, annotations and settings” for how to do this. (This is needed before you can start coding, as a workaround for this issue.)

  3. Visit the Discourse topic for which you want to see or add ethnographic coding.

  4. Click on the link “Coding View” below the topic’s title. You will see a simple HTML page of the same topic, paginated in case there are many comments. For example, if the original topic URL was
    then you should now be on

3.1. Coding of text

  • To create a new annotation (“ethnographic coding”):

    1. Select some text and click the annotation button that will appear.

    2. Type a substring of the code’s name you want to tag with.

      Multi-substring search in code names is not implemented yet, so whatever you type, including spaces, will be searched for in all code names. In practice, it works best to type starting with the first character of the code’s name but omitting all its ancestor codes, and to not omit any characters in the sequence.

    3. Choose the desired code name. Either select it from the proposed completions, or type any code name that does not result in a proposed completions. In the latter case, that code will be created on-the-fly when you save this annotation.

      As a special feature, it is also possible to create codes on-the-fly and sort them into the hierarchy in one step. Usually you would create codes on the first level only and later sort them into a hierarchy using the management functions. But if you want, you can also directly create them in the hierarchy by typing a code name that has " → " (space, arrow, space) between hierarchy levels, just the way that such codes are displayed in the auto-completion proposals.

    4. Click “Save”.

  • To edit an existing annotation, hover over text with yellow background, then click the pen icon :pencil2: in the popup that will appear.

  • To delete an existing annotation, hover over text with yellow background, then click the cross icon :heavy_multiplication_x: in the popup that will appear.

3.2. Coding of images


  • To create a new image annotation, pull up a rectangle around the image section you want to annotate, by clicking and dragging with the mouse pointer. Then select a code just as when coding text.

    You can create as many annotations on one image as you want, and their rectangles can intersect and contain one another.

  • To edit an existing image annotation, hover over the rectangle that represents the annotation to edit, then click the pen icon :pencil2: in the popover that will appear. Remove the existing code and select a new one. It is not possible to edit the size and position of the associated image selection; in that case, you’d have to delete and re-create the annotation with a different image section.

  • To delete an existing image annotation, hover over the rectangle that represents the annotation to delete, then click the cross icon :heavy_multiplication_x: in the popover that will appear.

3.3. Coding of videos

How to code a video. In the coding interface, you will see a link “See annotations / add annotations” below each video that can be coded. Click on it to go to the video coding interface, then click the top-left play button in the video to start it. Then:

  • To create a new video annotation:

    1. Wait for the position in the video where you want to start your annotation.

    2. Click the “New Annotation” button in the player’s toolbar. The player will pause and a popover window will appear.

    3. Enter a tag just as when coding text.

    4. Move the yellow triangle markers to adjust start and end position of your annotation. Note that annotations in edit mode are shown in yellow, and only then the markers can be moved.

    5. Click “Save”.

  • To view existing annotations:

    1. Click on the “Show Annotations” button. Bars will appear as overlay on the video, representing annotations with their start and end times. They appear as a stack in the order they were created, with the newest at the top and one annotation per row. Timestamps in the right corners indicate the creation times of the top and bottom visible annotations.

    2. Hover over the bars to see information about each annotation.

    3. Click on a bar to play the part of the video to which the respective annotation belongs.

  • To filter existing annotations by video time range in cases where the list is otherwise too long to work with:

    1. Click on the “Show Annotations” button. Again, bars represent annotations.

    2. Move the orange triangles in the top left and right corners to define the time range of the video slider that should be used as a filter to show annotations.

    3. Now, only the annotations that at least partially overlap with the selected time range are shown.

  • To edit an existing video annotation:

    1. Click on the “Show Annotations” button. Bars will appear as overlay on the video, representing annotations with their start and end times.

    2. Hover over the bars to show the popover window with information about the annotation.

      (You can also click on one such annotation to play its associated video snippet, and then hover over the bar in its new position near the video player timeline. The same popover with information will show.)

    3. Move the cursor into this popover window and click the pen icon :pencil2: that will appear.

    4. You can now remove the annotation’s code and add a new one, and also adjust the start and end position by moving the yellow triangles.

    5. Click “Save”.

  • To delete an existing video annotation, proceed as for editing an annotation but click on the cross icon :heavy_multiplication_x: instead of the pen icon.

Types of videos. Videos can be added to Discourse in several ways, and the process to code them is different due to legal and technical reasons:

  • Videos uploaded to Discourse. When a user uploads a video as .mp4 file while creating a Discourse post, it will be shown in the browser’s default player embedded into the post. Such videos can be coded directly. Currently, the upload file size limit is 100 MiB to keep our backups manageable – so, choose your MP4 video quality and encoding well!

  • Videos uploaded elsewhere and referenced as a file. Instead of uploading a video directly to edgeryders.eu, you can also upload it to a different platform like Imgur as long as that platform provides a direct link to the uploaded .mp4 file. When placing such a link on its own line in a Discourse post, it will result in an embedded video as well, and such a video can also be coded directly.

  • Videos uploaded to video platforms. You cannot code videos embedded from YouTube, Vimeo etc… This is due to legal reasons: YouTube’s terms and conditions for example allow showing the videos from their platform only with their player, but we need a special player to create the annotations. So before a coding project can begin, an administrator would have to edit these posts and transform such videos to one of the other two types listed above. Instead of replacing the original embedded video, the administrator can also add the codeable version below, hidden inside a foldable [details="Summary"] … [/details] element. If the video was created for the user’s post, this re-uploading will be covered by the Creative Commons licence that users grant for content they post on edgeryders.eu.

3.4. Coding of audio

Currently, coding of audio is covered by coding a video made from the audio and a still image.

At the start of a coding project, a platform admin might have to bring the audio into this format. This applies to cases where users added the audio by embedding a SoundCloud track or similar.

4. Managing codes, annotations and settings

The Open Ethnographer interface allows to administer codes, existing annotations and your user settings. Here’s how:

  1. Log in to edgeryders.eu as normal, with an account that has access to Open Ethnographer.

  2. Visit (and bookmark) the link to the Open Ethnographer interface: edgeryders.eu/annotator.

    You have to open this link in a new tab, or copy and paste it into the URL field of your browser. It will not work when you just click on it from inside Discourse to open it in the same tab. This is due to a Discourse bug / design issue.

How to use the different sections of the interface:

  • Overview. This shows a list of the last topics coded by you, so that you can quickly pick up on your work again.

  • Codes. Here, you can create, show, edit and delete ethnographic codes and their translations to various languages.

    Currently, codes form one global hierarchy, for all authors combined. After each code in the list, the number of annotations using it is shown in parentheses. To delete a code, you have to manually delete its sub-codes first, or move them to other parent codes. (This is a measure against accidentally deleting too much.)

    On the screen to edit a code, you can add translations of the code’s name into other languages defined in section “Languages”.

  • Topics. A list of all topics with at least one annotation. The list can be filtered by annotation author. Clicking on a list entry will bring you to the coding view for that topic so you can continue coding there. (To start coding in a new topic, you have to use the “Coding View” link at its top.)

  • Annotations. Shows the existing annotations of all ethnographers. You can see their data, filter by creator, and change the creator (but this will only be needed during imports and other administrative changes). All other changes to annotations are done in the coding view.

  • Languages. Allows to define the set of languages that can be used in code names.

  • User settings. Allows to configure some aspects of the Open Ethnographer behavior per user:

    • Language. Set and change your standard coding language. After changing this, all codes you create afterwards will by default assume that the code name is in the language you chose here. Existing codes are not affected. (You can change the language of any existing code in section “Codes”.) If you can’t find your preferred coding language in the list, create it first in section “Languages”.

    • Discourse tag. Set or change the coding project (“ethnographic corpus”) you’re currently working on, as represented by its ethno-* Discourse tag. It is important :bangbang: to keep this setting up to date, as it enables collaborative coding. When set to any ethno-* value, the codename auto-complete list will suggest all codes used in that coding project, independent of code author. When set to the empty value, Open Ethnographer will use the default behavior of showing a user all the user’s own codes, indepenent of coding project.

5. Using the API

We created an access protected custom API extension of the Discourse API that gives access to Open Ethnographer codes, annotations and ethical consent data. For the API documentation, refer to this topic:

6. Process for a whole coding project

In Edgeryders, we use Discourse tags to assign topics to Open Ethnographer projects. The presence of the project’s own tag tells the ethnographer that that particular topic is part of her project. We also use these Discourse tags to filter topics via the Open Ethnographer APIs.

This system allows easy reuse. The same topic that is relevant to today’s project could tomorrow also be used in another project. You can append as many tags as you want to the same topic, so there is no conflict.

6.1. Choosing a Discourse tag

Discourse tags that refer to ethnographic research projects with Open Ethnographer are named ethno-{projectname}, for example ethno-opencare.

You can choose the project name freely, it does not have to correspond to the name of an Edgeryders client project (as encoded in the different project-{projectname} tags).

6.2. Assigning the tag to an entire category

Most Open Ethnographer projects in Edgeryders are based on Discourse categories. For example, the OpenCare category is based on several categories. To assign a project tag to an entire category, do this:

  1. Navigate to the page of the category you want to monitor, for example https://edgeryders.eu/c/opencare/diy-and-open-source .

  2. “Infinite scroll” to the very last topic of the category, then scroll back up. This pre-loads every topic in the category into the browser’s memory.

  3. Click on the “bullet point list” icon under the name of the category, to the left of “Topic”:

  4. Two buttons appear. Click on “Select All”

  5. A wrench icon appears to the extreme right of the page. Click it.

  6. From the menu that appears, choose “Append Tags”

  7. In the text box that appears, type the tag, for example ethno-opencare

  8. Click the “Append tags” button.

If your project is based on more than one category, you will have to do this for every one of them.

6.3. Assigning the tag to a single topic

Sometimes an ethnographer or a community manager may find a topic that came out of a different project, but is happens to be relevant to the Open Ethnographer project at hand. For example, this is the case with several care-related projects coming to Edgeryders through the OpenVillage People and Projects category. To make a single topic part of the project at hand, do this:

  1. Navigate to the topic page, for example this one.

  2. Click on the pencil icon next to the title. A text box opens:

  3. Click in the text box and start to type the project tag, for example ethno-opencare.

  4. Click on the :white_check_mark: icon

6.4. Enabling collaborative coding

Open Ethnographer needs to know that you are now working on this new coding project, so it can propose you the codes used by anyone in that coding project (and exclude any others).

For that, choose the coding project’s Discourse tag in the following Open Ethnographer user setting: User Settings → [your user] → Edit User Settings → Discourse tag”.

6.5. Best-practice conventions for coding

This is treated in its own topic:

7. Archiving ethnographic data

For properly archiving the results of online ethnographic research, Open Ethnographer data have to be transformed, packed together with relevant metadata and uploaded somewhere “safe”.

While we don’t have this content fully developed and documented, here are some pointers to documentation about how this is being handled in our past and current projects involving Open Ethnographer:

8. Contributing to development

Open Ethnographer is open source software and you’re welcome to contribute:

  • Code. The code is hosted as project edgeryders/annotator_store-gem on Github. (The repo name is legacy and will change soon; it comes from an unmaintained project that we forked and used as our base software.)

  • Documentation. This document that you’re reading now is the documentation. It is provided as a wiki and you can edit it after opening an account on edgeryders.eu.

  • Issue tracker. Please contribute issue reports and feature requests in the project’s issue tracker on Github.

  • Discussion forum. If you have a feature request or idea but are not too sure about it and want to gather others’ input about it first, you’re welcome to do so in the Software (SSNA) forum category of our Discourse forum.

  • Support forum. If you need help with the installation or usage of Open Ethnographer, please post on the Open Ethnographer Manual topic of our Discourse forum – that is, simply comment below.


Looks great. Can’t wait to try it.

Thanks for this! Can we remove the requirement to add a comment to any annotation sooner rather than later? That will slow me down significantly—I have a system down and move very quickly assigning multiple codes to a group of text.

Also a way of separating out my codes from everyone else’s is sorely needed (both in terms of editing preexisting ones and in terms of other people’s codes not showing up as suggestions). Thanks again!

Thanks for the feedback! I added your requests to our issue tracker as issues #87, #88, #89. Will be dealt with before 2017-09-06.

If anything else arises, you can add issues directly to our Github issue tracker and assign it to our “Research ready” milestone.

@amelia I think you can now start tagging again now :slight_smile: The issues you raised are solved now, except visual distinction for own annotations (#89) which will follow later.

Also, all your tags have been imported. Import of existing annotations (#90) will follow within the next 4-6 days but should not prevent you from resuming the ethnographic markup work.

In addition, Daniel added a feature that allows you to filter the tree of ethnographic codes (tags) in the backend by author, so you can select to only see yours there. We figured it would be helpful to manage your hierarchy of tags.

Thanks @matthias! I’m looking forward to trying this all out.

Coding process itself feels great, thanks for the fixes! Will try playing with the hierarchies as well.

@alberto , is there a way to make the opencare explorer page work in this new framework? It still would be fabulous to be able to see what is still uncoded, but the way we had it before (showing new posts and sorting by how many many comments they have) would be useful still. (It seems I can go to OpenCare --> New but that shows me only 2 new posts)

Thanks, all!

Status update on the Import of existing annotations (#90): 6500 of the total 7100 annotations have been imported successfully. Annotations for 20 posts were lost as the posts did not exist on the new platform (causes not determined, most probably group description nodes which were deleted when re-organizing content).

The remaining ca. 600 ones will be manually matched to their new content by hard-working busy :bee: @anu Their quote differs in non-systematic ways from the current text due to changes made during import, such as emoticon conversions. So no proper way to do this with a script.

@amelia let us know at least a week in advance before you need the complete set of annotations online here for your research work. So Anu has enough time to get this done stress-free.

Out of the box with Discourse. There are actually two solutions:

1. Based on the project’s tag

Just go here: https://edgeryders.eu/tags/project-opencare?order=activity

Notice the ?order=activity at the end of the URL. You can click on fields to get your favourite reordering. “Activity” shows the topics in order of, well, activity: this includes creating the topic to begin with, but also adding new posts to existing topics (so far, so good). Unfortunately, you also get “uncodable activities”, essentially Likes and edits.


This only makes sense after we have decided which posts are part of OpenCare. There is a semi-automated way to do this from the categories: I’ll write a separate mini-instructable in this category.

2. Based on tracking categories

  1. Navigate to the page of the category you want to monitor, for example https://edgeryders.eu/c/opencare/diy-and-open-source .
  2. Click on the last button on the right under your avatar, next to the “New Topic” button. It is normally marked by an empty circle.
  3. Select “Watching”.

At this point, when you log onto Edgeryders you will see all new posts in this category as part of your notifications. However, beware: this may mean a lot of email messages.

Here is an instructable on assigning the project tag to entire categories and single posts:


@matthias We can have a call about this on your suitable timing :slight_smile:

Thanks! Looks good.

Hi @matthias and @alberto

I’m making a coding guide/course on OE, and I’ve realised that there doesn’t seem to be a way to merge codes in OE anymore, or to see the annotations associated with the codes.

Am I incorrect? If so, how would I do this?

My workaround for merging was to rename the code in question to the code I wanted to merge it to. But seeing the annotations associated with a code is important for forking codes (recoding already coded data under one code, say, ‘sustainability’, as ‘resilience’).


For the report and papers I just used GraphRyder to see the text associated for the code, but for recoding it’s important to be able to do this in OE itself.

You are right about this: issue #122 is about merging codes, issues #114 and #123 are about listing annotations.

How did you do this? If I try this, I get “Name has already been taken”. I seem to remember that we implemented this restriction later, so maybe you only used your workaround before we implemented that.

Right now, the closest you can get to merging codes is to group them below a common parent code in the hierarchy.

There is no workaround that I can think of. The most straight-forward way is to find some budget and ask @daniel to implement this (issues #114 and #123 as shown above).

Seems likely that I implemented this workaround before that restriction.

The old OE had the capability to do these things (however clunkily :smiley: ) — it’s important that we are able to merge and fork, otherwise cleaning up codes is virtually impossible. So if it means finding budget to do so, I highly recommend we do it.



Ok good :slight_smile: If (only if) @daniel wants to take this on, it should be around 600 EUR (12 h at 50 EUR/h). Paid by time, so this is only an estimate. If somebody else has to do it, it may be more, but 1000 EUR will be sufficient in all cases.

So once you found budget in that range, you can send me issue reports on Gitbub. :wink: Or more precisely, add a comment to the existing issue reports, mentioning that we can proceed with the implementation.

The price is right.

Good, will be implemented as requested. You may add deadlines where they are needed, otherwise it’s on a best effort basis (and it’s not a big “project” anyway).