#295 Create template in project docs for team directory
Closed: approved a year ago by bcotton. Opened a year ago by bcotton.

From the notes of the November 2019 Council face-to-face, here are the requirements for the directory. I believe we discussed having it be flexible that we could read it into a single directory but teams could also use the same input on their own documentation if they want to avoid duplication. That's not a hard requirement, but it sure would be lovely.

List of things we want in the directory:

  • Team name
  • Summary
  • Link
  • Some indication of it’s not a zombie

Things we want teams to tell people (all are required (except Other), but “none” is a valid answer)

  • Preferred Asynch communication channel (mailing list, discussion.fp.o, none, etc)
  • Preferred Synch (IRC channel, telegram, etc, none)
  • Issue tracker
  • Docs
  • Meetings
  • Other

(any venues listed above are subject to the Fedora Code of Conduct)


We already have the following pages:

I'll reuse those two, and add one more for Diversity and Inclusion.

Their sources are currently in the fedora-docs/pages repository, but I'll move them to the Fedora-Council/council-docs repository, so the right people (Engineering, Mindshare, and D&I representatives) get the correct permissions automatically. This move won't affect the website in any way btw, it's just a source change.

Then, I'll create a template for entries for each team. There are two approaches on storing these entries:

  1. Each team will be able to put their entry anywhere within their docs, so they can maintain it. And those entries then get included in the Engineering, Mindshare, and D& pages.

  2. All entries will be on a single place, maintained by the respective Council representative.

I think option 1 is what we want, right?

I think option 1 is what we want, right?

That would be preferred, this way it can be reused within the team's own docs if desired. The appropriate Council rep would add or remove includes (or whatever the specific mechanism) as teams pop up or go zombie.

Cool!

I need to check if there is a way to define all those fields at one place, but include just a subset in the directory.

So, this might be a hack, but I've figured it out!

We can have files with variables representing the individual team entries. Then, there is a 'rendering template' — a file that defines how those (and which) variables get rendered.

That's then put on a page as a series of include statements. It'll work across multiple repos, too.

Example:

Team definitions

team1.adoc:

:team_name: Team one
:team_description: We're just fantastic.

team2.adoc:

:team_name: Team two
:team_description: Nope, we're better!

A 'rendering template'

template.adoc:

== {team_name}

{team_description}

The directory page

include::partial$team1.adoc[]
include::partial$template.adoc[]

include::partial$team2.adoc[]
include::partial$template.adoc[]

teams.png

PR merged. Will open tickets for area reps to fill in the details

Metadata Update from @bcotton:
- Issue close_status updated to: approved
- Issue status updated to: Closed (was: Open)

a year ago

Login to comment on this ticket.

Metadata
Attachments 1
Attached a year ago View Comment