Agenda, Reports, and Minuting feature

[ewdurbin]

As requested by @brainwane, pulled from: https://mail.python.org/pipermail/pydotorg-www/2020-June/005432.html

Context:

Right now, www.python.org hosts the board meeting minutes
https://www.python.org/psf/records/board/minutes/ . We talked about
maybe also making space for working group/project meeting minutes, like
the ones I write up and currently host on the wiki (example:
https://wiki.python.org/psf/PackagingWG#Dependency_resolver_and_user_experience_improvements_for_pip
).

In the call, Ernest asked me to list what would be important in a
minuting package for www.python.org, distinguishing "required" from
"heavily encouraged" to "dream features".

Current workflow:

Right now, in order to minute meetings of Packaging WG-funded projects, I:

• use an Etherpad at pad.sfconservancy.org (just because it's a public
  and reliable EtherPad instance) and take notes with bullet points
• after the meeting, use its Export function to export to plain text
• mess with the formatting to adjust to MoinMoin wiki syntax
• go to https://wiki.python.org/psf/PackagingWG and create a new
  placeholder link in the table of meeting notes, annotating with the
  description, type (meeting notes), and date
• copy the text into that page, fix formatting, and hit Save
• erase the meeting notes from the Etherpad and hyperlink to the
  archived notes

What I want:

For the process in general, I have 3 core values:

• Ease of writing: it should be easy for me and for other meeting
  attendees to collaborate on writing minutes, live, during the meeting,
  in a reasonably lightweight syntax (such as Markdown)
• Privacy: as we write the minutes, they should be private to meeting
  attendees, so we can discuss things we then redact before sharing
  (vacations, burnout, criticism of other people or projects)
• Transparency: the final minutes should be public where anyone can read
  them, without having to log in anywhere, and linkable

As I understand it, a minuting system on www.python.org would have a
hierarchy like PSF -> Working Group -> Project. Example: PSF ->
Packaging WG -> Pip dependency resolver & UX improvements.

Required:

• Discoverability: the public minutes should be easy to find from a
  central project info hub, and show up in search engine results.
• Linkability: each meeting should have some unique URL or anchor tag,
  so that it's easy to link to minutes within an issue or mailing list post.
• Ease of formatting: some subset of HTML, Markdown, and
  reStructuredText should be supported.

Heavily encouraged:

• Automated table of contents on the Project page. Should include (by
  default) date and title of meeting, and it should be possible for me to
  also manually append (maybe in a separate list) links to relevant blog
  posts, reports, podcasts, etc.
• Automated table of contents on the Working Group page to all Projects
  underneath it.
• Finding aid/intro: A structure on each Project page that includes a
  freeform text field but also encourages certain fields (project name,
  list of participants, estimated start and end dates).
• Ease of formatting: Markdown support.
• Ease of import: a batch process to import old minutes from
  wiki.python.org, even if I then have to mess with formatting.
• Granular privileges: I'd like to let all my team members add minutes
  within our chunk of the site hierarchy.
• Ease of sign-on: Single sign-on with other PSF systems.
• Minutes structure: Structured text fields for meeting title, list of
  participants, discussion, and Next Steps/TODOs/Commitments.

Dream:

• Ease of navigation: from a particular minutes entry, I'd love to be
  able to click Next or Previous to go to the next/previous entry within
  that project chronologically.
• Ease of import: take an HTML import from Etherpad and strip the colors
  and other unnecessary syntax.
• Ease of import: On some note-taking platform (could be HackMD,
  Etherpad, Dropbox Paper, Google Docs, Nextcloud, or something else), I
  could choose an option to export to a new www.python.org minute. The new
  draft would autopopulate, so I could make changes and click Publish, and
  then it would show up at the right URL and be present in a Table of
  Contents automagically.
• Ease of formatting: support MoinMoin wiki syntax (so I can copy old
  stuff easily).
• Ease of reporting: this is really out-there, but if I could use some
  feature to automatically pull out the top-level discussion headings from
  each minute, and make a list of "here's what we discussed", then I could
  use that when publicizing the meeting notes, and it would make people
  more likely to read them.
• Analytics: so I could see who is linking to those notes and where
  they're being referred to.

[ewdurbin]

I propose that we begin implementing this feature by focusing on filling the role that wiki.python.org currently plays for PSF Board meetings. I'm going to ask for some input from PSF staff on what the basic needs are later, but for now...

Here is what I foresee as a very rough sketch of the basic models we would want in place to support generic use cases down the line (projects, working groups, subcommittees, etc), all of it is up for deeper thought and more informed decision (specifically names and relationships).

class Concern(models.Model):
    """ A "Concern" is a sort of Organizational Unit
        which can exist in a tree like structure """

    #  Name of the "Concern", Example: PSF Board, Packaging Working Group,
    #  or "Project"
    name = models.CharField(max_length=128)
    #  If applicable, a "parent" concern.
    #  Example: Finance committee of PSF Board,
    #  or "PIP UX Project 2020" under the Packaging Working Group
    parent_concern = models.ForeignKey('self', null=True, blank=True)

class ConcernRole(models.Model):
    """ A User's role within a concern, may be generic and come with
        certain specific MinuteItems that they are responsible for or allowed
        to provide """

    #  Name of the "Role", Example: directory/staff/officer (psf board)
    #                               project-manager/contractor/psf-staff (pip-2020-ux-project)
    name = models.CharField(max_length=128)

class ConcernedParty(models.Model):
    """ Effectively a "Group" for a given concern that makes managing
        access and reminders more straightforward. This may include the ability
        to email a notification that a meeting has been scheduled, remind
        attendees to submit reports, etc. """

    user = models.ForeginKey(User)
    role = models.ForeginKey(ConcernRole)
    concern = models.ForeignKey(Concern)

class Meeting(models.Model):

    date = models.DateField()
    parties = models.ManyToManyField(ConcernedParty)
    adhoc_attendees = models.ManyToManyField(User)

class AgendaItem(models.Model):
    """ Abstract Base Class for items such as reports, discussion topics, or
        resolutions which are submitted before a meeting.
        These are constructed together into a completed Agenda object. """

    meeting = models.ForeignKey(Meeting)

    class Meta:
        abstract = True

class MinuteItem(models.Model):
    """ Abstract Base Class for items such as notes or action items generated
        during a meeting.
        These are constructed together into a completed Minutes object """

    meeting = models.ForeignKey(Meeting)

    class Meta:
        abstract = True

[ewdurbin]

The current workflow for PSF Board Agendas and Minutes is as follows (to my understanding):

1. The date for the board meeting is decided
2. A skeleton agenda for that date is added to the private wiki containing

• Title and basic details such as conference call information and procedural notes as well as link to previous meetings minutes for approval.
• Board and Staff Monthly Reports section
  • One heading for each PSF Staff member
  • One heading for each PSF Board director
• Working Group Reports section
  • One heading for each PSF Working Group (Grants, Sponsors, Marketing, Jobs, Trademarks, Fellows, Packaging, Infrastructure, Scientific Python, Funding Work Group)
• Section for Votes approved by Email
• Section for Votes Approved by Working Groups
  • One heading for each PSF Working Group
• Section for Consent Agenda Resolutions
• Section for New Business
• Section for Discussions

3. Meeting occurs
4. Attendance, Vote results, and adjournment are noted by staff member for inclusion in minutes
5. Draft of minutes is created from the agenda, including information from the meeting (attendance, votes, adjournment, etc).
6. Draft minutes are published to the private psf-important mailing list
7. Any edits are submitted to the draft minutes by staff and directors
8. Draft minutes are approved by the board at the next board meeting
9. Minutes are copied into Django Admin (https://www.python.org/admin/minutes/minutes/) and then published to https://www.python.org/psf/records/board/minutes/

[berinhard]

Thanks for gathering this info @ewdurbin! I have a few quick comments, questions and ideas to contribute with.

About the rough data modeling you're proposing, I think it plays nice for what we've discussed so far. I really liked the idea of having an abstract AgendaItem and many custom implementations as we may need while this minutes app (may we call it that?) evolve. But the only thing that got me thinking is this ConcernRole.

From my a first look, it seemed that it's representing some kind of concern types, I don't know. It was difficult to me to imagine other attributes or usages for this model, but probably my lack of familiarity with the domain plays an important role here. Given that, I was wondering if, for an initial version, the ConcernParty.role can't be simple range of possible choices for now. We could store the value in an attribute, such as role_type, and expose it via this role property, so we'll have room for proper refactoring in the future if we need to move this information to a proper model.

Another thing I was thinking about are the nested items in the agenda... I don't know if it's something we should be concerned about right now, but as a suggestion to support that, we could add a self-reference in the base AgendaItem model named parent which defaults to null. What do you think? Maybe this requirement is already a valid one given the hierarchy you've mentioned of one heading for each PSF Staff member, under the "Board and Staff Monthly Reports section" for example.

[berinhard]

A suggestion for a good starting point would be to have an interface were a Board/Staff member can schedule a new meeting. The page can be simple form with a datetime input. The backend would:

1. Create a new Meeting;
2. Organize the meeting's parties (PSF and Staff members);
3. Create the default AgendaItems @ewdurbin have described;
4. Display the meeting agenda populated with the defaults values;
5. Route so people can access the agenda in a private mode (only for logged and concerned users);

What do you think?

[ewdurbin]

The biggest reason to have any hierarchy above a Meeting object is so that it can be displayed in a navigable way.

I could imagine looking for minutes from all PSF activities in the following ways:

• All minuted meetings from any entity in a given time period
• Minuted meetings from a given entity in chronological order

Thus, I think we want to establish some model for organizing Meeting objects, though that could certainly be added later once the core functionality is in place.

[ewdurbin]

About the rough data modeling you're proposing, I think it plays nice for what we've discussed so far. I really liked the idea of having an abstract AgendaItem and many custom implementations as we may need while this minutes app (may we call it that?) evolve.

Yes, the board specifically has some required items that have mild complexities for its agenda and minutes. As an example there are a few types of Resolutions that are addressed: 1) Resolutions already settled by email vote 2) Resolutions which will go on a "Consent Agenda" for discussion before vote and 3) Resolutions which will be voted on during the meeting. Not all Meeting types will need that amount of specificity, so abstracting seems great to offer lighter weight options.

I unfortunately the minutes app is taken as greenfield, but we should be able to implement these features into that app since the end result will be Minutes objects published to the site.

From my a first look, it seemed that it's representing some kind of concern types, I don't know. It was difficult to me to imagine other attributes or usages for this model, but probably my lack of familiarity with the domain plays an important role here. Given that, I was wondering if, for an initial version, the ConcernParty.role can't be simple range of possible choices for now. We could store the value in an attribute, such as role_type, and expose it via this role property, so we'll have room for proper refactoring in the future if we need to move this information to a proper model.

I think that can certainly be left for later decision/discussion. Goal is just to be able to better automate reminders and notifications for people who have responsibilities in forming a given agenda/minutes without pestering everyone.

Another thing I was thinking about are the nested items in the agenda... I don't know if it's something we should be concerned about right now, but as a suggestion to support that, we could add a self-reference in the base AgendaItem model named parent which defaults to null. What do you think? Maybe this requirement is already a valid one given the hierarchy you've mentioned of one heading for each PSF Staff member, under the "Board and Staff Monthly Reports section" for example.

At this time, nest-able AgendaItems should be considered unnecessary I believe. They may have a "title", "summary", and "body" depending on how they are presented. Detailed sub-points on an item could be in the body.

[berinhard]

Great @ewdurbin! I'll work on an initial modeling so we can talk more about this in a PR. OK?

[brainwane]

Also, as a person who frequently takes and tracks meeting minutes for the current funded pip resolver work, I look forward to being an alpha or beta tester for this functionality on www.python.org.

[brainwane]

Is this a feature that is likely to happen anytime soon? As I get going on my Python packaging work I'd like to settle into a good place to keep notes and reports.