[Archivesspace_api_doc_adhoc] Next steps

[Mayo, Dave]

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: <archivesspace_api_doc_adhoc-bounces at lyralists.lyrasis.org> on behalf of "David W. Hodges" <dwh2128 at columbia.edu>
Reply-To: ArchivesSpace API Ad Hoc Working Group <archivesspace_api_doc_adhoc at lyralists.lyrasis.org>
Date: Saturday, December 14, 2019 at 9:09 AM
To: ArchivesSpace API Ad Hoc Working Group <archivesspace_api_doc_adhoc at lyralists.lyrasis.org>
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 <dave_mayo at harvard.edu<mailto:dave_mayo at harvard.edu>> 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<mailto:Archivesspace_api_doc_adhoc at lyralists.lyrasis.org>
http://lyralists.lyrasis.org/mailman/listinfo/archivesspace_api_doc_adhoc<https://urldefense.proofpoint.com/v2/url?u=http-3A__lyralists.lyrasis.org_mailman_listinfo_archivesspace-5Fapi-5Fdoc-5Fadhoc&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=_Mv1dY22K7jvT5MD7xjbvGVzRDOUMhx4WYcnPSIzYnE&m=rmgMoXUFMCYHBAXISLuREMyU0URDS-BAwcyNeOcNf0c&s=907SrI4ewoccpzaoFvHPyhTYOoO5z7EM-EDvwNVN6rE&e=>


--
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: <http://lyralists.lyrasis.org/pipermail/archivesspace_api_doc_adhoc/attachments/20191217/1f08b323/attachment-0001.html>