2018-02-28 Meeting notes
Date
, 1:00pm CST
Attendees
Discussion items
| Item | Who | Notes |
|---|---|---|
| Roll call and note taker | Bobbi Fox taking notes | |
| Data Dictionary ownership and maintenance | The Reports subteam has been working on a data dictionary, with a demo at https://desolate-tundra-60608.herokuapp.com/, and they have questions about where/how the data dictionary could be maintained, including these activities:
Where/how could the Tech Docs subteam be involved? Laney:would it flow out of the release process? At least the tables for the data dictionary would get updated with the release as well as the cross-walk, with descriptive metadata to be added later. Is it technical documentation or user documentation? Scott: Could this be part of the QA/Test process to get some eyeballs on it? Bobbi: who's using this? what is the lag time if we put metadata descriptions it on the subteam? Laney: originally thought it was for the developers, but more & more seems like the archival users who have access to the db might use it in SQL. Thinks the metadata could be added later. Laney: the Reports subteam is under the UAC. Is it more a user doc or a technical doc? Max: seems like table & field information is one thing, but the description and example data is something that is so particular to an institution, so getting more of user vibe. Trevor: thinks it's a mixed bag. Dallas: A lot of the descriptions seem like the tooltips in the staff interface; is there a way to re-use this? Laney: The tooltip language is from the user documentation group. Laney: it was suggested that this was a cross-council kind of thing; doesn't know how that works. Laney: also trying to figure out where the Data Dictionary is going to live, who has permissions, etc. Do people get to modify it directly, do we do pull requests? etc. Scott: seems like there isn't a single group that's responsible for it. No conclusion reached Laney's ok with that, it was more that she wanted to make sure that this was discussed with this group. The cross walk should be ready at end of March, and we may revisit this. | |
| API docs, Jira ANW-199 | All | Request to look at ANW-199 - Getting issue details... STATUS and update http://archivesspace.github.io/archivesspace/api/#get-post-search The documentation is in two places: A request that Tech Doc reviews documentation on what the API actually requires. Laney: "We use slate and yard" which pulls together the endpoint information in the code itself, so not part of the markdown documentation. The API documentation says that all you need is the :all_ids parameter, but you also need the :page parameter when using :all_ids. Need help with verbiage. Proposed: :id_set or :all_ids is required. then, under the Boolean all_ids: Boolean all_ids – Return a list of all object ids (must also include the page parameter) Dallas references crud_helpers.rb, and notes that the page parameter seems to be processed first, before you even get to all_ids. We now establish that /search has a different logic than /respositories/{n}/resources... Trevor suggests the inconsistency is programmatic, rather than documentation. Scott is going to add a comment to the Jira. |
| Review issues in tech-docs GitHub | All | https://github.com/archivesspace/tech-docs/issues/2 -- there's a pull request https://github.com/archivesspace/tech-docs/issues/8 Anyone knowledgeable about this issue? Laney is not sure about 6; she's recommending people go to 8 if they can. Trevor: we can have a base assumptions that the techdocs repo refers to the current version, so we should uniformly refer to 1.7 or higher. Listing the packages needed is an administrator issue. Feels it's more detail than is needed. Scott: agrees that just referring to version number is sufficient. Laney is worrying about the "lone arranger" people who might need more help, but doesn't know where the line is drawn. Trevor: can we link to some external to ArchivesSpace documentation on installing Java on the various machines. Dallas: this actually was raised in the course of support for his course, and actually got resolved. Scott: does adding language that "this documentation applies to 2.3" help? Trevor is volunteering to try to update the language |
| Review pull requests in tech-docs GitHub | All | Closed: https://github.com/archivesspace/tech-docs/pull/9 Open: https://github.com/archivesspace/tech-docs/pull/3
https://github.com/archivesspace/tech-docs/pull/4 - approved for merge – Trevor just did it https://github.com/archivesspace/tech-docs/pull/7 - approved for merge – Trevor just did it https://github.com/archivesspace/tech-docs/pull/10 - Rachel is taking the comments, and thinking that we need documentation for setting up subdomains, and wondering if we expand the provisioning, then include information on locking down ports. Rachel is happy to flesh out the prefix section. She'll cancel the pull request, then reissue a new one. She'll put a note in, saying she's closing the pull request for now. Trevor asks about when we stop documenting for past versions? Bobbi's latest pull request will be reviewed after the meeting. |
| Workplan Goal 1. Enhance provisioning documentation | Updates (Ran out of time) | |
| Workplan Goal 2. Enhance plugin documentation | Updates (Ran out of time) | |
| Documentation platform | Feedback from TAC call on readthedocs, etc. | |
| Wrap up and next steps | Migrations documentation which is PDF may get pull-requested into the rest of the document. |