Collaboration roles and hierarchy
Collaboration on the glossary is a function of access rights to the repository, the types of contributor roles we need, and your familiarity using GitHub. We assume most collaborators won't have much GitHub experience, if any at all. Thus we aim for using GitHub in a way that lowers the bar to contributions as much as possible while still using GitHub's workflow to help regulate glossary progress. Collaborators must be self-regulating, diplomatic, and working within the established protocols to ensure collaboration is systematic and productive. Be sure to read up on Using issues and Using issue labels.
On this page:
"Owner", "managers", and "outside collaborators" are GitHub terms in relation to repository access. We adopt the terms here for convenience because you'll see them used in the GitHub interface if looking in the right places. These 3 classifications of collaborators (including editors, writers, and developers) have 'write' access to the repository, which is the primary way we work on this project. No pull requests will be accepted (except, perhaps, from developers in relation to Jekyll site development).
The glossary is semantically structured against Schema.org to give attribution to contributors. The attribution is manifest to humans on glossary pages via YAML Front Matter (data serialization), and to machines as JSON-LD (structured linked data). All collaborators with rights to the repository will contribute in one or more of the following roles, which are relevant to linked data attribution:
- owner
- editors
- writers
- developers
- advisors
For those curious about the semantic side of this project, technical specs are forthcoming to describe how it works in relation to the technologies involved under the hood (Jekyll, YAML, Liquid, HTML, and JSON-LD). Or look at the repository file tree. It's all there in linked files and markup.
The human side of it all is detailed in the relevant sections below.
The owner is the creator of the CSF organization ("organization" being a GitHub term) and the sole owner among organization members. The owner serves as the acting editor-in-chief of the glossary and makes decisions about final production, technical development, partner relations and so forth. The owner also deals with high-level dispute resolution issues, should that ever be a problem.
Managers are the other members of the "organization" besides the owner. Combined, they represent CSF, which deals with a lot more than just the glossary project.
Manager responsibilities for the glossary project are:
- Write/edit wiki documentation.
- Design/build the production platform. See also:
- Project phases (Phase III)
- Production glossary structure
- Help editors moderate/facilitate Issues through collaboration.
Managers will be credited in the list of contributors on the glossary index (homepage) in standard order, which is alphabetical by last name.
"Outside Collaborators" (another GitHub term) are people who work in content-as-service fields (typically) and contribute to writing and editing glossary definitions.
These people have 'write' access to the master repository, meaning they install the GitHub desktop client and clone the master repository to their local machines, make changes there to definition files, then push (commit) their changes back to the master repository without interference. The following diagram depicts the whole idea.
Note: Due to how GitHub is designed, not everyone in the Outside Collaborators list may be associated to the glossary repository, thus would not be glossary collaborators. You have to check which repository a given person is associated with by clicking their name and seeing what repository matches up.
Collaborators who are associated with the 'csf-glossary' repository can contribute as writers and editors, respective to a given role's responsibilities, but can not serve both roles on the same draft files. In other words, if you write a definition, someone else must review it with the editor hat on.
Additional conditions are noted below for each role type.
(In this project, the labels, 'editors' and 'reviewers' mean the same thing — people who review the copy efforts of definition writers. The two terms are relevant to YAML and JSON-LD development, but for purposes of collaboration, they mean the same thing.)
Ideally, contributing editors are people who are editors by trade, recognized in their field, and/or have published a relevant book on the subject of a given definition.
Editors review and correct definition copy from writers. They also have more decision-making power as far as draft development goes, within the collaborative framework.
The scope of editor responsibilities are:
- Help admins to follow and moderate Issues (discussions, debates, statuses...), to ensure they progress and remain productive.
- Fix typos, broken links, and Markdown formatting in draft articles without need for commenting about it in the term's respective Issue history.
- Make near-final to final draft changes based on existing Issues raised from everyone else.
Editors are credited in the global contributors list on the glossary index (homepage). They also get added to the (semantic) linked data as ‘editor’ for the respective definition files they serve as editor for (i.e. they appear to machines, not humans.) Multiple editors can exist for a given definition file over time.
(In this project, the labels, 'writers' and 'authors' mean the same thing — people who contribute definition copy. The two terms are relevant to YAML and JSON-LD development, but for purposes of collaboration, they mean the same thing.)
A writer contributes copy to definitions. They can not be authors of a published book in the field. We let the glossary be an opportunity for less known writers to get some attribution.
The scope of writer responsibilities are:
- Add new draft files for target terms.
- Write the initial draft definition copy, partially or entirely.
- Edit existing drafts that are not in a 'claimed' status.
- Initially add any figure for a definition, where warranted.
Writers get their names on the individual definitions they contribute copy for, and to the global contributors list on the glossary index (homepage). They also get added to the (semantic) linked data for the same definition files.
A developer works in relation to the owner, contributing code or markup to the design/development of production glossary. Developers may or may not be managers too. Developers get their names added to the global contributors list on the glossary index (homepage).
An advisor is a “hands-off” type of collaborator who gives constructive feedback for improving any aspect of the production glossary outside of one of the other defined roles.
Advisors have the following abilities to help guide the project:
- Propose new glossary terms
- Challenge an existing term to have it changed or removed as a principle entry
- Challenge the topic depth and/or scope of an existing draft file
Commenters get their names added to the global contributors list on the glossary index (homepage) if and after glossary changes are made due to their feedback.
Inquirers are people who don't have — nor want — a GitHub account, but still have an itch to scratch about the project. If this is you, get it off your chest in the Glossary category of the CSF Discussion boards. We welcome whatever gripe you may have. Please keep it professional.
Tip: You can sign up in the discussion boards using a Twitter or GitHub account. Hence, if you do sign up in the discussions boards via a GitHub account, your immediately qualified to collaborate at higher levels.
You must request outside collaborator rights to modify glossary content (create, edit, or delete files, improve metadata or semantics, etc.)
If you would like to do this and have a GitHub account, go to the REQUESTS TO COLLABORATE issue and make a reply comment with the following information:
- Your first and last name
- An affiliation website URL
- Your country of residence
- The primarily role you expect to contribute by
Why do we request this information?
We need this information to give you attribution on the glossary index (all collaborators), and on the individual definition files you might work on (writers only). The information is also necessary for the metadata and linked data built into the glossary architecture.
When your rights are granted, you'll be added to the list of Outside Collaborators with associated rights of access to the "csf-glossary" repository.