From dave_mayo at harvard.edu Fri Dec 13 14:33:28 2019 From: dave_mayo at harvard.edu (Mayo, Dave) Date: Fri, 13 Dec 2019 19:33:28 +0000 Subject: [Archivesspace_api_doc_adhoc] Next steps Message-ID: <0FF8DF85-7F82-4B86-BF5E-D1F32442DA21@harvard.edu> Hi all, Sorry it?s been radio silence from me for a while ? I wanted to get in touch before our various holiday breaks and whatnot, with a discussion of what next steps will look like. I?m thinking these should happen sometime soon after the new year, ideally. Our next steps should be some kind of triage (i.e. selecting which endpoints need documenting most) and then distributing the work. I?d like to come to an agreement as a group on how to proceed with each of these steps; I?m going to outline a couple ways I could see it working up front so we have something to bat around. Triage/figuring out which routes need attention: - we could just individually bump priority on routes we know are bad, clear those, and then do another round of triage (maybe with more investigation ala option 2 below) then. - we could divide the routes evenly? by capacity? and have each person check N routes and mark which ones need attention - Or something in the middle, like categorize the routes somehow and investigate specific categories? Personally, I?m having a hard time saying what?s right here, and that?s making me feel like doing 1 just to have some concrete progress on the table isn?t the worst idea - and maybe exposure to more routes while fixing it will give some ideas for how to improve triage methods? Then, splitting the work: I think due to differing capacity and volunteer nature, this has to be pretty driven by individuals - I think ?grab routes with high priority and work on them? is more or less a given. I think we might want to specify some low-effort check-in/check-out guidelines, i.e. maybe whether a person should only assign themselves a route right before they get to work on it, or if grabbing a bunch that you have in mind is better, and so on. People with more PM experience than I in this group, so PLEASE chime in here ? -- Dave Mayo (he/him) Senior Digital Library Software Engineer Harvard University > HUIT > LTS -------------- next part -------------- An HTML attachment was scrubbed... URL: From dwh2128 at columbia.edu Sat Dec 14 09:09:20 2019 From: dwh2128 at columbia.edu (David W. Hodges) Date: Sat, 14 Dec 2019 09:09:20 -0500 Subject: [Archivesspace_api_doc_adhoc] Next steps In-Reply-To: <0FF8DF85-7F82-4B86-BF5E-D1F32442DA21@harvard.edu> References: <0FF8DF85-7F82-4B86-BF5E-D1F32442DA21@harvard.edu> Message-ID: Hi Dave, thanks for checking in on this! I'm sorry to say I have done nothing on it since the last call, but I look forward to getting into it again soon (realistically, probably after the holidays). For the moment I have a suggestion and a question: Suggestion: What if each of us took one route of our choice (check out a row in the spreadsheet) and roughed out what we take to be complete (or improved) documentation? Then we could compare notes and come to some agreement on a model to use going forward. This could save some rework down the road if we have very different styles of documentation going on. I'm thinking a lot of routes will also have very similar documentation and could be templatized. A question: I noticed in the screen cast (maybe this was a local branch, I'm not sure?) that Python examples were written using ASnake. I've been wondering, are we going to presume Asnake as the method? I ask somewhat selfishly as I don't use ASnake myself, though I'm probably an outlier. Maybe we should have non-snake examples along side, to minimize dependencies? Any thoughts? Best regards, David On Fri, Dec 13, 2019 at 2:33 PM Mayo, Dave wrote: > Hi all, > > Sorry it?s been radio silence from me for a while ? I wanted to get in > touch before our various holiday breaks and whatnot, with a discussion of > what next steps will look like. I?m thinking these should happen sometime > soon after the new year, ideally. > > Our next steps should be some kind of triage (i.e. selecting which > endpoints need documenting most) and then distributing the work. I?d like > to come to an agreement as a group on how to proceed with each of these > steps; I?m going to outline a couple ways I could see it working up front > so we have something to bat around. > > Triage/figuring out which routes need attention: > > > - we could just individually bump priority on routes we know are bad, > clear those, and then do another round of triage (maybe with more > investigation ala option 2 below) then. > > - we could divide the routes evenly? by capacity? and have each person > check N routes and mark which ones need attention > > - Or something in the middle, like categorize the routes somehow and > investigate specific categories? > > > Personally, I?m having a hard time saying what?s right here, and that?s > making me feel like doing 1 just to have some concrete progress on the > table isn?t the worst idea - and maybe exposure to more routes while fixing > it will give some ideas for how to improve triage methods? > > > Then, splitting the work: > > > I think due to differing capacity and volunteer nature, this has to be > pretty driven by individuals - I think ?grab routes with high priority and > work on them? is more or less a given. I think we might want to specify > some low-effort check-in/check-out guidelines, i.e. maybe whether a person > should only assign themselves a route right before they get to work on it, > or if grabbing a bunch that you have in mind is better, and so on. People > with more PM experience than I in this group, so PLEASE chime in here ? > > > > -- > > Dave Mayo (he/him) > > Senior Digital Library Software Engineer > Harvard University > HUIT > LTS > _______________________________________________ > Archivesspace_api_doc_adhoc mailing list > Archivesspace_api_doc_adhoc at lyralists.lyrasis.org > http://lyralists.lyrasis.org/mailman/listinfo/archivesspace_api_doc_adhoc > -- David W. Hodges Special Collections Analyst Columbia University Libraries Butler Library 535 West 114th St. New York, NY 10027 212 854-8758 -------------- next part -------------- An HTML attachment was scrubbed... URL: From dave_mayo at harvard.edu Tue Dec 17 15:56:34 2019 From: dave_mayo at harvard.edu (Mayo, Dave) Date: Tue, 17 Dec 2019 20:56:34 +0000 Subject: [Archivesspace_api_doc_adhoc] Next steps In-Reply-To: References: <0FF8DF85-7F82-4B86-BF5E-D1F32442DA21@harvard.edu> Message-ID: Hi David, No apologies necessary ? I?ve also not done much since last call; I think a lot of people are in ?get stuff done before the holidays? rushes ? I think the suggestion is a good one. I?m not as sure about templating, simply because if somethings similar enough that it applies across a swath of routes, it ought to be added to the autodocs. Then again, given the state of and difficulties involved there, templates might end up being a good stop-gap, or we might find commonalities that are hard to pick out programmatically. So, re: ASnake for the examples: I asked this question of the program team earlier, with the outcome being ?for now at least, prefer ASnake for the Python examples? for the following reasons: - Lora/Laney are using ASnake when writing Python examples (there are thus far just two) - there?s not a single Python HTTP library that everyone uses; requests is really popular, but aiohttp and others are also in wide use - to actually make it ?no dependency? it would need to be stdlib http.client, and people in general aren?t writing scripts with http.client - The ASnake client layer is a thin wrapper over requests, so transposing into requests isn?t very difficult If you wanted to also provide an example in another python client, you could, but it?d need to be inlined into the same example block (because Slate example tabs are limited to one per language supported by Slate), and I?d be a little worried about some endpoints having examples for X, Y, and Z and some having just X or Y, etc. -- Dave Mayo (he/him) Senior Digital Library Software Engineer Harvard University > HUIT > LTS From: on behalf of "David W. Hodges" Reply-To: ArchivesSpace API Ad Hoc Working Group Date: Saturday, December 14, 2019 at 9:09 AM To: ArchivesSpace API Ad Hoc Working Group Subject: Re: [Archivesspace_api_doc_adhoc] Next steps Hi Dave, thanks for checking in on this! I'm sorry to say I have done nothing on it since the last call, but I look forward to getting into it again soon (realistically, probably after the holidays). For the moment I have a suggestion and a question: Suggestion: What if each of us took one route of our choice (check out a row in the spreadsheet) and roughed out what we take to be complete (or improved) documentation? Then we could compare notes and come to some agreement on a model to use going forward. This could save some rework down the road if we have very different styles of documentation going on. I'm thinking a lot of routes will also have very similar documentation and could be templatized. A question: I noticed in the screen cast (maybe this was a local branch, I'm not sure?) that Python examples were written using ASnake. I've been wondering, are we going to presume Asnake as the method? I ask somewhat selfishly as I don't use ASnake myself, though I'm probably an outlier. Maybe we should have non-snake examples along side, to minimize dependencies? Any thoughts? Best regards, David On Fri, Dec 13, 2019 at 2:33 PM Mayo, Dave > wrote: Hi all, Sorry it?s been radio silence from me for a while ? I wanted to get in touch before our various holiday breaks and whatnot, with a discussion of what next steps will look like. I?m thinking these should happen sometime soon after the new year, ideally. Our next steps should be some kind of triage (i.e. selecting which endpoints need documenting most) and then distributing the work. I?d like to come to an agreement as a group on how to proceed with each of these steps; I?m going to outline a couple ways I could see it working up front so we have something to bat around. Triage/figuring out which routes need attention: - we could just individually bump priority on routes we know are bad, clear those, and then do another round of triage (maybe with more investigation ala option 2 below) then. - we could divide the routes evenly? by capacity? and have each person check N routes and mark which ones need attention - Or something in the middle, like categorize the routes somehow and investigate specific categories? Personally, I?m having a hard time saying what?s right here, and that?s making me feel like doing 1 just to have some concrete progress on the table isn?t the worst idea - and maybe exposure to more routes while fixing it will give some ideas for how to improve triage methods? Then, splitting the work: I think due to differing capacity and volunteer nature, this has to be pretty driven by individuals - I think ?grab routes with high priority and work on them? is more or less a given. I think we might want to specify some low-effort check-in/check-out guidelines, i.e. maybe whether a person should only assign themselves a route right before they get to work on it, or if grabbing a bunch that you have in mind is better, and so on. People with more PM experience than I in this group, so PLEASE chime in here ? -- Dave Mayo (he/him) Senior Digital Library Software Engineer Harvard University > HUIT > LTS _______________________________________________ Archivesspace_api_doc_adhoc mailing list Archivesspace_api_doc_adhoc at lyralists.lyrasis.org http://lyralists.lyrasis.org/mailman/listinfo/archivesspace_api_doc_adhoc -- David W. Hodges Special Collections Analyst Columbia University Libraries Butler Library 535 West 114th St. New York, NY 10027 212 854-8758 -------------- next part -------------- An HTML attachment was scrubbed... URL: