Normalise regions #485

dougaitken · 2018-10-16T16:12:07Z

To allow for better matching and locations, we need to have predefined options for "region".

For example. For global reach, the default should be Worldwide. I made the first major change of this in #175

As mentioned in #480, we don't have a defined option for United States / US / USA.

I mainly use US but I'm open to discussing from Americans about what they'd use most often.

If a company is limited to one country, then that should be listed, otherwise, we could use options like Worldwide, APAC, Europe, US (USA), Africa.

I don't know what would be best / easiest. Either splitting via continent or region so I'd love to open this up for discussion

The text was updated successfully, but these errors were encountered:

nylen · 2018-10-17T04:21:45Z

I think US should be USA. "US" or "United States" are commonly understood, but to me more ambiguous, and sounds almost like it could be Micronesia or Mexico.

I think if we're going to clean this up and make the Region field something from a predefined list, then we don't really need both region fields any more (the short one in the readme, and the possibly longer one in the company profiles). We can now take data out of the company profiles and stick it on the main page of the site pretty easily, so we can delete this column from the readme.

Anything we do here is going to require a good bit of manual cleanup, though. And of course the only way to get people to stick to a convention is to enforce it, so we would add more bot checks too.

I think it would be worth doing though - if we can come up with a good scheme here, then it will make a nice filter on the main page of the site.

Looking at the data in the "short region" field in the readme, here is what we have now:

(44 distinct values)

Value	Count
Worldwide	135
(blank)	133
USA	17
US	17
Europe	9
United States	7
Brazil	4
USA & Worldwide	3
UK & Europe	3
PST Timezone	2
US and Canada	2
UTC-8 to UTC+2	2
WorldWide	2
UK	2
US Only	2
UTC-8 to UTC+1	2
United States and Canada	2
USA, UK, (EST, GMT)	1
Latin America	1
USA, UK, Israel	1
USA, Worldwide	1
USA, Offices in Boston, MA	1
US, UK	1
US East Coast	1
Americas	1
US & Canada	1
Costa Rica & Worldwide	1
UTC+2 +- 2	1
Western North America	1
US / Worldwide	1
Pacific Time Zone (PT)	1
US, UK, Europe	1
US & UK	1
South Africa	1
US & CA	1
USA & India	1
EU & Worldwide	1
UTC-9 to UTC+1	1
UTC-7 to UTC+1	1
India	1
Europe and Americas	1
South Korea and Japan	1
Worldwide (U.S. Timezone)	1
Germany, The Netherlands, Spain, Chile	1

And in the "Region" field in the company profiles:

(155 distinct values)

Value	Count
(missing)	167
Worldwide	38
Worldwide.	5
Europe	5
USA	4
US and Canada	2
Open to worldwide employees provided that they can do some timezone overlap with US business hours.	2
&yet has one office located in Richland, WA. Currently ten people are working remotely out of Seattle, Portland, Folsom, Phoenix, Denver, Kansas City, Frankfurt, Oslo, and Melbourne. The most significant timezone difference is 17 hours.	1
We have employees all around the world, from across the US to the UK to South Africa to the Philippines. Most are currently located in North America, a number travel frequently, and some even work nomadically.	1
U.S. citizens, non-citizens who are nationals of the U.S., or people who have been admitted to the U.S. for permanent residence and hold a valid green card.	1
Worldwide. Right now we have folks distributed throughout North America and Europe. We have one brave soul from Australia, and another from New Zealand. More are welcome.	1
The bulk of our engineering team is in Europe so we generally prefer candidates working from timezones that are within 3 hours of UTC (+/-).	1
Worldwide - Acquia is an international company with office locations around the world. Remote positions are available globally.	1
USA only for the time being: many of our contracts with the US government require employees to be in the US.	1
Main office is located at Geneva, Switzerland. There is one small office in Wroclaw, Poland where 3 developers are working from. We have also one person working from Turkey. There is at most 2 hours time zone difference between team members.	1
Worldwide, but we work primarily on US timezones.	1
United States, India, Poland, and more	1
Our remote engineers work the same hours as our New York and London offices depending on what team they are on. We welcome people in all time zones that are willing to work in EST or GMT.	1
Latin America - Anexus is a regional company with offices in Costa Rica but a team distributed across 9 different countries from México to Argentina. The company has available positions in Latin America.	1
US-based employees only.	1
UTC-8 to UTC+2	1
US-based. We currently have team members in Cincinnati, Louisville, Denver, and Boulder.	1
Worldwide, company offices are spread throughout the world and all open job listing offer remote.	1
Worldwide - our team members hail from all over, every continent except Antarctica (so far!) - this means over 50 countries around the world.	1
Worldwide - Axelerant team members work from home, cafes, or co-working spaces.	1
We currently have employees in the U.S. and in several European countries.	1
Worldwide - Bandzoogle is remote-only.	1
Currently we are only set up for US-based remote employees.	1
US, currently.	1
We have employees all around the world, with the bulk of our engineering team in Europe, so we generally prefer candidates working from timezones that are within 3 hours of UTC (+/-).	1
A team of developers (and designers) located around the US, Canada, and Croatia.	1
US Remote (any timezone)	1
Buffer employs people worldwide	1
Worldwide, or "home based", their open vacancies can be search by location or role	1
CareMessage employs people worldwide	1
Remote friendly worldwide	1
We have employees in several different countries around Europe, regardless of their physical location. We have some nomadic employees as well!	1
Worldwide - Mainly US based employees but with one in Brazil and another in Australia. A map shows employee rough locations on the About Us page	1
Mainly USA but some UK	1
Not specified.	1
The main offices are in New York, San Francisco, Santa Monica, Portland and Seattle but we also have many team members working remotely from Asia, Europe and North/South America.	1
Our team is primarily located in the U.S. and Canada -- however, we have others in Europe, Costa Rica, and Philippines! Instead of making rules about location, we set expectations around teamwork and communication. We welcome team members from all over the world, as long as they are able to structure their work day in a way that allows for collaboration. Some of our public sector contracts require team members to have US citizenship or residency.	1
Worldwide - A globally located community of talented business analysts, developers and designers.	1
Anywhere	1
Worldwide, but remote technical roles are USA only.	1
We are open to members anywhere. (We know the possible Mars One members will have problems with real-time communication but we are planning a tachyon beam or a wormhole bridge.) Talking seriously, There are legal issues for associating people living outside Brazil, but that is a problem that we will be happy to solve when needed. Besides that we must consider language limitations on the role you will play at Colivre. Our primary language is Portuguese.	1
Convert.com employs people worldwide.	1
Most of the team in East Coast. Preference for people in the same timezone.	1
For technical hires, we're looking anywhere in the United States. For non-technical hires, there may be other considerations, like needing reps in particular cities or countries.	1
Worldwide! We have or have had people based in Germany, the UK, the US, and Canada. We also have a few nomadic folks who have worked from Australia, Korea, and Portugal!	1
Worldwide - We have employees that work from the America to Europe, and even some of us are working nomadic by now :)	1
Worldwide given job openings	1
North and South America. We like to have at least a 4-hour overlap when we can coordinate on a project if the need be.	1
We are open to new team members living anywhere in the world.	1
Worldwide See our about page to see where people are based: https://duckduckgo.com/about	1
Costa Rica, US, Anywhere.	1
We have employees in all around the world.	1
Our employees are spread around the globe. At the moment you can find Emsisoft staff in Armenia, Austria, Canada, Germany, Hungary, India, Indonesia, Italy, Netherlands, New Zealand, Philippines, Portugal, Romania, Russia, Spain, Ukraine, United Kingdom, and the USA.	1
Envato is a fast growing company with headquarters in Melbourne.	1
Europe.	1
All stuff located all over the world	1
It doesn't matter where our team members are located, as long as they are passionate about what they do.	1
Worldwide, but mostly Europe	1
Scotland, UK based company, remote worldwide	1
Our positions require you to reside in western North America (Pacific or Mountain Time Zones)	1
Worldwide, with team members across the world.	1
Worldwide (See above)	1
We are primarily interested in hiring U.S. remote employees.	1
Worldwide - We have employees in almost every time zone in the world! From San Francisco to London to Australia, we hire people regardless of their physical location. We even have nomadic employees!	1
Worldwide. We have GitLabbers on every continent (except Antartica... yet).	1
We are region-agnostic, and simply look to hire the best engineers in the world, regardless of location.	1
Gorman Health Group employs talented brainmatter throughout the United States.	1
About a third of us are in the Bay area, but we have several other US locales represented, including Los Angeles, Portland, Milwaukee, Miami, and Las Vegas.	1
US - We currently have 1 Full-time employee remote team in the domestic US. Worldwide - We currently have 2 international remote teams: One mostly in South America, one mostly in Europe. Our international employees are currently directly contracted.	1
Currently, our full-time staff is based entirely in the United States.	1
Dev team is UK/EU, Sales&OPS are US/UK	1
We hire engineers worldwide.	1
Remote position are open to any U.S. citizen whose permanent address is in the United States.	1
Our Product & Engineering team is based almost exclusively in Europe and Africa. The number of North American outliers might grow but it’s EMEA for now. The rest of the company stretches into the Americas also. Our locations are based on timezones - we have certain timezone restrictions for each role (anywhere within EMEA for P&E) and don’t mind where you are or how much you move around within those timezones.	1
US and UK based employees.	1
Worldwide - We support working remote but we are very open (and support it even more) if you want to come and work in the Netherlands (it's a great country ;) )!	1
South Africa (some positions are open to the rest of Africa)	1
Most of us are in the US and Europe, but we're open to consider other locations as long as we have some timezone overlap.	1
We have employees in many different countries around Europe, America and Asia, some of them are located at Melbourne but location is not important.	1
US and Canada: Victoria, BC Haida Gwaii, BC Portland, OR San Francisco, CA Denver, CO Atlanta, GA Columbus, OH	1
Remotes are preferred to be on New York time or similar, as our main offices are on New York time, but there are various remotes throughout the globe.	1
Dependent on position.	1
All employees are US-based.	1
Worldwide - iwantmyname has been remote since day one.	1
Jackson River currently only has US-based employees.	1
Kiprosh is an international company with office locations in Chicago, USA and Mumbai, INDIA. We have clients from USA, Canada and Hong Kong and thus we work in timezone that has overlap with our client's timezone.	1
Primarily based out of San Francisco, but KissMetrics have a strong remote presence all throughout the world.	1
Company is based in Barcelona, Spain but you can work from everywhere	1
All of our customers and employees are in the USA, and we currently are focused on that region only.	1
Europe, US, Brazil, Canada. Most of our people are in Europe, so we try to ensure some overlap in terms of timezones.	1
We have offices in London, Boston, and San Francisco, but many of our employees work fully remote. Even those who work close to the offices often work from home. We have employees in Central America, all over Europe, Pakistan, and many other countries.	1
Localistico is focused in UK and Spain currently, but you can work from wherever part of the world you like.	1
6 countries 52 cities	1
UTC-9 to UTC+1. Time shifting at the boundaries is typically necessary.	1
Remote locations include U.S., Canada, Europe, and South America.	1
We're just hiring EU-residents with a working permit. Freelancers willing to do contract work might apply from anywhere, but won't be eligible for a full-time job inside the company.	1
US-based employees	1
Anywhere in the world, as long as you're willing to overlap at least 4hrs a day with 10-6pm US Pacific time.	1
We primarily accept applications from the UK and European countries, as we work best with an overlap of ~5hrs with offices in Scotland.	1
Worldwide!	1
Worldwide - We have employees that work from the America to Europe.	1
Customers are mostly based in the US.	1
Our employees are located worldwide - in Australia, United Kingom, Colombia, South Korea, Canada, and the United States.	1
Pacific Time (PST) to Central European Time (CET)	1
Nuna is headquartered in San Francisco, but approximately 20% of our team works remotely across the U.S., including a large cohort in the D.C./Baltimore-area near government clients. Check out www.nuna.com/careers to see what open roles are available to remote candidates.	1
US based only we work with the government and can't flex on this	1
UTC-8 (Pacific) to UTC+1 (Central Europe)	1
Currently, we only accept portuguese speakers candidates that can work in a time range compatible with the BRT (UTC -3) business hours.	1
OmniTI is open to hiring worldwide, though some projects may prefer team members located in Western Hemisphere time zones. Don't be afraid to ask!	1
Open to all countries.	1
US only.	1
Payfully employs people worldwide	1
Currently all employees are based in the US, but we are open to working with anyone who resides within the GMT -7 (Pacific Time) and +1 (Central European Time) zones.	1
Our main office is in Paris and we can help on relocation, but most people in the company work remotely. Currently we have people in north-america (where we have offices in Ann Arbor MI), Western and Eastern Europe and the Middle-East, but we hire on competency alone, not on time-zone affiliation.	1
We have people all over our lovely little planet.	1
US, APAC, and EMEA.	1
Worldwide - The team is distributed around the world, with headquarters in Santa Monica, CA and coworkers in all time zones of the continental United States, Nigeria, Philippines, India and Thailand.	1
US-only - we have many clients that require certain background checks to be performed, and certain work that can only be performed by US citizens (no clearance required).	1
Our employees are based in Europe. Most are in the UK and France.	1
Currently, US-based only	1
Our Team is spread all across India.	1
Team is distributed across the United States, Canada, New Zealand, the United Kingdom, Nigeria, and Germany with the highest concentration in the U.S.	1
Sensu is open to employees from the United States and Canada.	1
We support working remotely from Europe and the Americas.	1
Anywhere in the United States	1
Remote positions are available globally.	1
Skillcrush is located in the US but we are open to candidates from all around the world.	1
We have Seoul, Busan, and Tokyo office but if you want to work remotely, it doesn't matter.	1
As of the summer of 2016, we're focused on US-friendly timezones - you should be able to easily overlap at least 5 hours of your work day with the US Eastern time zone.	1
Worldwide - "Work Where You Want"	1
We'd prefer continental US and Canadian employees in Eastern Standard Time, but we're totally open to international employees if the fit is right.	1
Stripe support remote working, according to Cristina Cordova - BD @ Stripe "From Seattle to New York to Europe".	1
Both full-time employees and student notetakers are spread worldwide.	1
TaxJar is currently hiring developers in the United States.	1
Worldwide.	1
We're only looking for people who are resident in, and eligible to work in the UK.	1
United States.	1
Worldwide! The US region has the majority of employees, but we have a presence in Europe and Latin America as well.	1
Worldwide - Toggl don't hire on location	1
Toptal employees are spread throughout the world.	1
Work from anywhere in the world : )	1
United States	1
Worldwide - we have team members in many different countries and timezones.	1
We are company from Slovakia (EU).	1
Our headquarter is in Moscow, Russia.	1
Worldwide Company.	1
From the Work with us FAQ Can international applicants apply for positions with the Wikimedia Foundation? We are a global organization and welcome international applicants for positions with the Wikimedia Foundation. Please see our “Pluralism, internationalism, and diversity” policy .	1
Most of the team work out at the office in Old City, Philadelphia, and others spread from Arizona to Serbia.	1
Worldwide - Work anywhere More than two decades ago, Wolfram was already a pioneer in geographically distributed teams. Today, some positions require being based at one of our corporate locations around the world, but many have full geographic flexibility after an initial training period.	1
We have offices in Göttingen and Hamburg in Germany.	1

Code to extract data

const { parseFromDirectory } = require( './lib' );
const _ = require( 'lodash' ); // npm install --no-save lodash

const data = parseFromDirectory( '.' );

const allRegions = data.companies.map( c => {
    return ( c.profileContent.region || '(missing)' )
        .replace( /\n/g, ' ' )
        .replace( /<[^>]*>/g, ' ' );
} );

const regionsTableMarkup = _.sortBy(
    _.toPairs( _.countBy( allRegions ) ),
    p => -p[ 1 ]
).map( p => p.join( ' | ' ) ).join( '\n' );

console.log( regionsTableMarkup );

Nirvikalpa108 · 2018-10-18T14:34:17Z

Hi @dougaitken and @nylen, thanks for starting this conversation which is really worthwhile.

I agree that USA sounds good.
Do you think we could use the following convention for the region field?
1 country = country
2+ countries in the same region = region
2+ regions = worldwide

So, for example, if the company has employees in 1 country, eg the UK, then we put UK in the region field. If they have employees in 2 countries, eg the UK and Germany, then we put Europe. If they have employees in the UK and US, then we put Worldwide. Does that make any sense?? Lol I don't know if I've just made it more complex! Let me know!

With regard to the naming of regions, whilst I have an intuitive feel as to which regions I would use, I decided to take a look at the UN Statistical Devision's method, which is as follows:

Africa
Northern America
Latin America & the Caribbean
Asia
Europe
Oceania (this includes Australia)

I quite like this. Let me know what you think?

Also, @nylen I like your suggestion that we could put the region in the company profile and then repeat that in the Readme file. Have I understood you correctly? Please correct me if I'm wrong! Thank you guys

nylen · 2018-10-19T00:55:38Z

Wow, sorry about the mis-clicks there.

I quite like this. Let me know what you think?

I like it, except I think we should split out "Latin America" and "Caribbean" because together that is very long.

Let's simplify a bit further.

Region can be 1 country (USA), 1 region, or a list of multiple regions, or Worldwide.

If there are, let's say, 3 or more regions, then we'll keep the original list in the data here, but collapse this down to Multiple on the main page. The site can show the full list of regions on the company profile page.

And yes, we'll remove the Region column from the readme, but still show it on the main page of the website via magic.

I think this is workable. In a little while I'll post a list of what I think needs to be done to make this happen.

Nirvikalpa108 · 2018-10-19T01:16:23Z

Sounds good @nylen. Sorry if this is a really stupid question, but what's the difference between the main page and the readme that you've noted?
So, we're removing the Region column from the readme, but it's still on the main page and company profile?
Thanks 👍

nylen · 2018-10-19T01:30:46Z

The difference is that we can make any page of the site say whatever we want, as long as the data comes from somewhere. For now it mostly matches the format of the input files (main readme and company profiles), but it doesn't have to.

The site is automatically generated by code that parses the data out of the readme and the company profiles, and then reconstructs it in the format we want for the website. Again right now this format is basically the same as the input data, but it doesn't have to be.

In this case, we'll leave the region info in each company profile, clean it up for all profiles, and remove it from the readme, so that it only has to be written and updated once by us. Then we'll use that code to copy the region from each company profile to the main page of the site.

In short: it takes some preparatory work, but we can let the robots do the boring, repetitive tasks like copying data, as much as possible.

Nirvikalpa108 · 2018-10-19T01:51:10Z

Nice nice, I understand now thank you! 😃

nylen · 2018-10-21T03:46:28Z

I'll post a list of what I think needs to be done to make this happen

Add some validation code (optional for now) to show a list of the companies that have a Region field that doesn't match the format above, or that have a different region between the readme and the company profile. It's going to be a lot of errors and we'll need to fix them a few at a time.
Fix the region field in all the company profiles. For now we'll probably want to leave the region field in the readme, and make it the same as what's in the company profile. This will also mean changing things like (for example) "UTC-8 to UTC-4" to "USA" or "North America". Here it would be best to research a bit about each company, or ping the person who originally added the profile, but it doesn't have to be perfect.
Decide what to do about the "extra" text in the Region field of the company profiles (I pulled all the values for Region in my comment above, and there is a lot of extra stuff there). We could allow this text to appear below the list of predefined regions, or we could move it to a different section of each profile.
Once everything is ready, enable the validation code from the first step for all new PRs - this will make sure the data stays in good shape.
Build a filter for region on the main page of the site.

Nirvikalpa108 · 2018-10-22T20:46:58Z

Hi @nylen
This looks good to me!

Regarding the "extra" text in the Region field, do you think it's worth adding this to the "Remote Status" section of the company profile? I'm inclined to keep the text and just put it somewhere else in the profile rather than deleting, as some of it is quite useful.
Also, do you think one of the items to add to your list is to change the Contributing Template and Company Profile template so that contributors know about the new rules for regions?

Thank you!:smiley:

nylen · 2018-10-24T05:44:09Z

Yes to both of those questions (move the extra text to the "Remote Status" field, and indicate the new rules for regions in our template files).

Nirvikalpa108 · 2018-10-25T21:26:11Z

Great @nylen! So, just to reiterate, we need to do the following (in this order of priority?):

Indicate the new rules for regions in our template files
Fix the region field in all the company profiles (move any "extra" text in the Region field of the company profiles to the "Remote Status" field.)
Once everything is ready, enable the validation code from the first step for all new PRs.
Build a filter for region on the main page of the site.

I've left out the validation code action to show the companies not adhering to the new region rules, because I assume this will be so many of them anyway 😂 and since it will be such a manual process, maybe it's not super necessary. But if yourself or someone else could write that code quickly, maybe this would be helpful?

Please let me know what you think! I'm happy to have a shot at changing the rules in the template files and slowly chipping away at the manual edits 😄 Thank you

nylen · 2018-10-26T01:10:10Z

Sounds good. I'm thinking having the validation code in place, but leaving it as optional, would be useful in order to be able to generate a list of remaining issues whenever we want it. Are you able to run the existing validation code on your computer?

Definitely don't let that keep you from getting started though!

dougaitken · 2018-10-26T08:30:04Z

For context @Nirvikalpa108 - the readme list was the main list previously, James did the work to make it fancy and live on the website so we can move things away from that main list.

Ideally, everything lives in the company profile, we can then use that data if needed.

Thanks for your thoughts on this Amina!

Nirvikalpa108 · 2018-10-30T06:33:09Z

Sounds great @nylen. I should be able to run the validation code. If I have any problems, I'll let you know, thank you 😃
Thank you so much for giving me this context @dougaitken, you're a star! I really appreciate it! 😊

Nirvikalpa108 · 2018-10-30T13:08:46Z

Hey guys, so here is a draft of the language I propose to put in the Contributing Guidelines and the Company Profiles - example.md pages so that contributors know what to put in the region field. If it's rubbish, no worries at all, it's just a first draft! I appreciate all your feedback! 😃

Contributing Guidelines
Number 5 - If you adhere to the protocol for listing the countries or regions for remote positions (as explained in the company profile - insert link)

Do we want to remove the asterix saying that this is optional and make it a requirement? I think it should be a requirement given it would improve the site's functionality (eg the search function) and I think that's why this issue #485 exists, but let me know if I've misunderstood.

Do you want to list the rule itself in the Contributing Guidelines or just link to it in the company profile page? Do you think contributors will follow the link and read it?

Company Profiles - example.md
Region
Where are remote employees accepted? List either 1 country (eg USA), 1 region (eg North America), a list of multiple regions, or Worldwide.

Here is the list of regions:
Africa
North America
Latin America
Caribbean
Asia
Europe
Oceania (this includes Australia)

If there are 3 or more regions they can be listed on the company profile page, but noted as Multiple on the main page.

Guys, this advice for the company profile page seems really long compared to the guidance for the other sections. This is just a first shot. Keen to get your thoughts. Once we're happy with wording I'll do a PR to submit changes. Thank you!:sunglasses:

Nirvikalpa108 · 2018-10-30T13:08:47Z