Better documenting the calls

[nicola]

General problem

In our calls beyond the important discussions (that need to be written down), we often have a list of todos (that many will want to see). We often do wrap-ups, we post notes in different repos & so on.

Problems in the 8th Aug call

We took notes but we post them in different places:

• IPLD notes: IPLD spec refining call - round 1 #124 (comment)
• all-hands notes: Sprint: Aug 8 → Aug 14 #133 (comment)
• pubsub notes: Sprint call notes from 08 August 2016 libp2p/research-pubsub#1

Problems:

• It is very difficult for new comers to find out what happened
• It is difficult for us to go back and have a read about what happened, and search to past notes
• It is difficult for us to understand what are the action points of the different sessions

Possible solutions

• ONE REPO: Have one repo for notes from every call, say /ipfs/calls and in there we create an issue every single time we have a call (/ipfs/pm has too much going on for proposing calls, and other pm stuff)
• IN THE SPRINT ISSUE: Every sprint issue has links to the notes, or the notes are new issues in different repos that link back to the sprint (so one can go and have a look at the sprint links to find out)

Maybe there are other solutions I haven't considered, I think having the repo using issues as notes, or even committing notes as files, can really be a great solution to this problem.

---

cc @RichardLitt, @diasdavid, @flyingzumwalt, @em-ly, @jbenet

[daviddias]

Agree that is very hard to digest the notes if you were not in the call.

IN THE SPRINT ISSUE: Every sprint issue has links to the notes, or the notes are new issues in different repos that link back to the sprint (so one can go and have a look at the sprint links to find out)

This is what we do right now, right?

ONE REPO: Have one repo for notes from every call, say /ipfs/calls and in there we create an issue every single time we have a call (/ipfs/pm has too much going on for proposing calls, and other pm stuff)

We could add a folder to ipfs/pm with the notes of the meetings, so that they are easy grep'able

[nicola]

Your 3rd solution, is a really great idea!

This is what we do right now, right?

Yes almost. In the way we do it right now, it is very difficult to read the links to the notes amongst questions, people's update & so on. This is not organized and easy to work with (for my taste 🍔 of course)

[RichardLitt]

I'm happy to try uploading notes as markdown files into a folder called ipfs/calls. I think that this would work well, because it would:

a) Enable us to PR them, so others eyes can make sure that the notes are good. This would ensure quality in the notes, both pre-PR by the editor, and post-PR by reviewers
b) grep
c) Finite representations of a point in time that is not stored in what I am realizing more and more is a GitHub silo.

Let's try putting notes in a folder, and go from there?

Proposed format: 2016-08-06 IPLD.md

Should cover the basics.

[flyingzumwalt]

👍 Agreed that we definitely need to try something. I think the approach @RichardLitt outlines here sounds strong enough that it's worth trying next week. (Or even try it with this week's notes too so we can look at 2 weeks worth of notes).

[jbenet]

• +1 for capturing notes in one place. will also make sure notes dont die to pads' expiry
• Please don't add another notes repo. for the calls during sprints, just add the notes in this repo or in ipfs/notes.
• format: don't use spaces please. spaces are very annoying to deal with in commandlines. pls use another delim, like dashes: 2016-08-06-IPLD.md. (yes dashes delimit the datetime too. it's ok.)

[nicola]

brilliant effort everyone!

[RichardLitt]

Since the README is currently in a state of revision, I am going to keep this open to remind myself to do this every week.

[daviddias]

We have been doing this every week, I believe it is time to consider this issue done? Closing, reopen if necessary.

[RichardLitt]

Opened a relevant PR in #270.