📗 Open Ethnographer Manual



We have a first (still a bit rough) version of Open Ethnographer for Discourse now. Here are instructions for its usage – extend the wiki as needed.


1. Introduction

2. Getting access

3. Using the backend

4. Using the frontend

5. Using the API

6. Assembling a project for coding

7. Coding

8. Reporting issues and feature requests

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’/’tag 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 any part of Open Ethnographer (frontend or backend), you must first become a staff user (moderator or admin). So, ask an admin to make you moderator, and explain why.

3. Using the backend

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

  2. Visit (and bookmark) Edgeryders’ custom administration backend: edgeryders.eu/administration. (This link will open in a new tab, and will not work when opened from Discourse in the same tab, which is due to a Discourse bug / design issue.)

  3. Under “Tags”, you can create, show, edit and delete ethnographic codes. Currently, tags form one global hierarchy, for all authors combined. After each tag, the number of annotations using it is shown in parentheses. To delete a tag, you have to manually delete its sub-tags first, or move them to other parent tags. (This is a measure against accidentally deleting too much.)

  4. Under “Collections”, you will be able to create, show, edit and delete intersecting sets of existing tags, for the purposes of a study. For example, export of annotations will work on the basis of these collections. (This part is not yet implemented.)

4. Using the frontend

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

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

  3. Click on the Coding view link under 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
    This will eventually be simplified with an icon on the topic’s page to switch to the Open Ethnographer view, but for now this is how it works.

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

    1. Select some text and click the annotation button that will appear.
    2. Type the beginning of the tag’s name you want to tag with, omitting all ancestor tag names. (Important: Multi-substring search is not implemented yet, so type the whole name of your tag without omitting parts or you won’t find it in the proposals.)
    3. Select the right tag from the proposed completions. Proposals will include all tags, independent of their author.
    4. Click “Save”.
  5. To edit an existing annotation, hover over text with yellow background, then click the pen icon :pencil2: in the popup that will appear.

  6. 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.

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. Assembling a project for coding

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 the Discourse tags as filter options in the Open Ethnographer APIs.

This system allows easy reuse. The same topic that is relevant to today’s project, tomorrow could be reused for a different one. You can append as many tags as you want to the same topic, so there is no conflict.

6.1. Naming convention

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

7. Coding

This is treated in its own topic:

8. Reporting issues and feature requests

For now, please report them in Edgeryders normal Discourse issue tracker. (We might eventually split out Open Ethnographer into its own repository, but for now it’s simpler this way.)

:green_book: Discourse User Manual for edgeryders.eu
Making Open Ethnographer code hierarchies useful
Using the edgeryders.eu APIs
Understanding the tech stack
MENA Open Village Coding: Lessons Learned
Former category intro text ("About the Future Makers category")

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).