Contributor profile pages

[rviscomi]

I'd like to pitch an idea for discussion: year-agnostic profile pages for each contributor.

For those who contribute to multiple annual editions, some of their metadata is duplicated across the config files, like name and social links. Authors also have bios in the year's base template. It may be useful to deduplicate the metadata about a contributor that doesn't change over time, like their name, social links, and bio, from the metadata that is year-specific, like the teams and chapters.

So for example, I could add basic metadata about myself to /src/config/contributors/rviscomi.json (or .yaml):

{
  "name": "Rick Viscomi",
  "avatar_url": "https://avatars0.githubusercontent.com/u/1120896?v=4&s=200",
  "github": "rviscomi",
  "twitter": "rick_viscomi",
  "bio":  "Rick Viscomi is[...]"
}

Then in 2019.json and 2020.json I only need to map my contributor ID rviscomi to the teams I contributed to those years. We could also get info about which chapters I contributed to from the YAML in the chapter markdown files.

All of this contributor info could be made publicly available via endpoints like /<lang>/contributors/<id>, eg https://almanac.httparchive.org/en/contributors/rviscomi. I imagine the page being somewhat similar to dev.to/rick_viscomi:

• profile photo
• name
• bio
• social links
• snippets of chapters I've contributed to (as an author, reviewer, analyst, editor, or translator)
• badges representing teams I've been on and the number of years I've been a contributor (gotta catch 'em all!)

Right now only authors have bios and they're only visible on the chapter pages. This proposal would enable all contributors to have bios on their personal profile pages and it'd be easier to go back through all of their contributions over the years.

Curious to hear if this is something contributors want, whether there are any unforeseen technical complexities, or if there are any other ideas for ways we could utilize a page like this to showcase contributors' work.

[tunetheweb]

Good idea. I’ve been thinking our contributor page is a bit light and think we should have links back to chapters they worked on. Saying someone was an author isn’t much use, without saying what chapter(s) they authored on!

However I still think it’s good to highlight the contributors for each year. To say we 96 contributors to 2019 edition (and who they were), and that there were 116 contributors for 2020 (and who they were). So I’d probably keep the contributors page as it is now as well and link to the individual profile pages from it. Maybe also have an /en/contributors for all years? Or alternatively have just that one page but allow it to be filtered by year as well as team.

But definitely agree we should avoid repeating data across years. Not sure individual files per contributor are a great idea - could slow things down to read many of them either at start up or dynamically when a page is requested, e.g. if we keep the contributors page, or in chapters with lots of contributors - unless we have name as well as if in the 2019.json / 2020.json and accept that repetition. So I’d probably go with three files:

• 2019.json - remove contributor info except ids
• 2020.json - remove contributor info except ids
• contributors.json - full details keyed by id

With the linting we have, the chance of bad config getting I there is very low, so think maintaining in combined files like this is fine. Maybe if we start to get a lot of extra meta-data to build full profile pages, so we get concerned about size of JSON file, then that can go in individual files and contributors.json is just the core info needed for each contributor.

[rviscomi]

However I still think it’s good to highlight the contributors for each year. To say we 96 contributors to 2019 edition (and who they were), and that there were 116 contributors for 2020 (and who they were). So I’d probably keep the contributors page as it is now as well and link to the individual profile pages from it.

+1 let's keep the existing /<lang>/<year>/contributors pages. We should also think about how to link the Contributors and chapter pages to the profile pages.

Not sure individual files per contributor are a great idea - could slow things down to read many of them either at start up or dynamically when a page is requested, e.g. if we keep the contributors page, or in chapters with lots of contributors - unless we have name as well as if in the 2019.json / 2020.json and accept that repetition. So I’d probably go with three files

Either way. With contributor-specific files, it's easier to maintain. At deploy time we can run a script to bundle them up into a single config, or "hydrate" the year-specific config files with the perennial metadata. Having files for each contributor enables us to render the profile pages based directly on "file_exists" checks rather than loading all contributor data and testing whether a contributor key exists. Tradeoffs with each approach, but I'll defer to you on implementation.

[rviscomi]

I started looking into this and I'm feeling more enthusiastic about going in this direction. I like the idea of a page where contributors could list all of their multi-year contributions across the entire project.

A few concrete suggestions:

• Give each contributor a src/config/contributors/<id>.json file and document all of the required/optional fields in the wiki
• Remove the contributors object from the annual config files, instead annotate team memberships in the teams object with a members array
• At build time, compile all contributors into a config file consumable by the server and use it for validating and serving requests to the /<lang>/contributors/<id> path
  • This should be done at the same time as chapter generation (or at least reusing parts of its pipeline) so that we can map contributors to chapters and their roles, and also inject author bios into the generated chapter templates
  • <year>.json config files should also be processed so that each contributor can have details about when they contributed and what teams they were on
• Create a new year-agnostic Jinja template and implement a design (TBD) that showcases their contributions