-
Notifications
You must be signed in to change notification settings - Fork 3
ERDWMeet20220713
Summary from: Eric Zinda
In attendance: Olga Zamaraeva, Dan Flickinger, Luis Morgado da Costa, Alexandre Rademaker, Eric Zinda
Agenda:
- Discuss finished work from the last week: https://github.com/delph-in/docs/wiki/ERDWActiveWork
- Lots of rich discussion points in @arademaker 's comments on prototypes
- Discuss what to do at summit
- Decide on next work to do
Meeting:
We started by getting feedback on the Conceptual doc prototype:
- Overall thoughts and comments?
- Do you think it works for the target audience?
- Do you think it succeeds in targeting both audiences? I.e. if we deleted the original, are we good with that?
There was consensus that it was easier to read and also that it isn't quite right yet. Lots of discussion ensued:
Dan wanted clarity on what were the principles used when rewriting the document so that it might be replicated by others and not just intuited by Eric. Eric walked through the outline of what he was trying to do here.
Alexandre reinforced that terminology is not per se bad and it in fact opens up new worlds, we should not shy away from it. It lets you deal with new concepts etc. Eric pointed out that learning the terminology for a programming language is good, but learning the terminology for how to build the compiler, while useful, isn't usually necessary unless you are going to add code to the compiler.
This led into Dan pointing out that we may really need to separate our thinking into two concepts: Tutorial vs. Reference documentation. Tutorial-type documentation is meant to get you up to speed, possibly use vaguer language to get you started but teach you the terms and concepts you need to understand the rest. And: you may never go back there again once you are up to speed. Reference-type documentation is meant to be referred to over and over and very precise. Olga pointed out that being a little imprecise to get you started is inevitable if you are teaching someone something new and cited several examples. She also pointed out that as you get deeper, you'll understand where the metaphors fell down and have to relearn it a little.
Dan confirmed that (basically) the original essence page had the goal of being a tutorial as well as describing the base value of the ERG, but the target audience was the prototypical linguistic grad student, and now we are talking about a different smart audience. Eric said that he tried to keep those same goals, but target both audiences. Luis proposed the idea to have a "Must Read This First" intro tutorial as a way to clearly identify what the document is.
Dan also pointed out that it may be very hard for those firmly in the Delph-in world to write the tutorial type information since they are already at that next level and it is hard to go back. Eric pointed out that there may not be a lot and we might be able to cover with just a couple of people.
(Action: Added to Active Work List) Since we're still ruminating on this notion of Tutorial vs. Reference it may make sense to have the group loop back and look at it with this perspective and see how it holds up. It may help with some of the objections or point to a version 2 of the prototype that gets it more cleanly in the tutorial camp.
Overall there seems to be three workstreams here to resolve:
- Tools: What tools can help to autogenerate useful information for reference pages and/or check to make sure they are up to date. We need a mockup of what a page "could" look like to give us something to think about. (Action: Added to Active Work List, the group volunteered Francis Bond, but we need to ask him)
- Examples: We need to gather some examples of good reference pages to riff on. (Action: Added a discussion topic here to collect good examples)
- Prototypes: We need to build another reference page prototype to see how they compare and what similarities are. (Action: Added to Active Work List)
There was more consensus that this prototype might eventually work for all audiences. The format changes and (some) simplified language seemed to work here.
Luis felt like the MRS text might not work for all folks and would at least like to see alternative visualizations (DMRS, etc) as an option as he's a visual learner. He also proposed that we may want to find a way to future proof the docs by comparing agains the current version of the DRG and, e.g. produce errors if the MRS shown in the docs isn't a top interpretation. Alexander reinforced the point that we need a better way to keep the docs and artifact in sync. He felt that the comments in the files, exposed in the documentation are good but we need a little more integration. We need to explore extracting all the value we can from that integration. He also pointed out that the wiki form may not be right for this type of documentation, especially if it is being autogenerated.
Olga pointed out that there are lots of examples of good reference documentation (not just in linguistics) out there that we should steal from.
We all agreed that we need to explore what the format is/should be and what should be in it.
Dan proposed that we should do a second page on another phenomenon: eric will find one. Dan suggested Relative clauses?
Eric walked through a proposed slide deck to kick off the plenary session. Seemed like it would inspire some good discussion.
Home | Forum | Discussions | Events