The Technical Documentation sub-team (TechDocs) facilitates maintenance and enhancement of all ArchivesSpace technical documentation.
This page is intended to document the internal processes of the Technical Documentation sub-team to facilitate continuity between terms.
Maintain ArchivesSpace technical documentation in tech-docs Github repository
Collaborate with ArchivesSpace program team to prioritize, assign, and work on issues in the TechDocs Jira board.
When new versions of ArchivesSpace are released, review release notes, providing edits/suggested changes to developers.
Identify documentation maintained by other sub-teams, link to it as appropriate, and avoid duplication of effort.
Solicit feedback and contributions from the community
Encourage ArchivesSpace community to submit issues regarding documentation directly to the tech-docs repository or contact sub-team members via email to suggest improvements.
Monitor listserv for issues for which further documentation would be helpful and file an issue in the TechDocs Jira board to be prioritized and assigned.
Review, manage, and promote Awesome ArchivesSpace.
Perform outreach and make ArchivesSpace community aware of TechDocs
Promote TechDocs work and facilitate broad community knowledge by linking to relevant portions of documentation in listserv responses and other communications.
Suggest the inclusion of relevant links to TechDocs within documentation maintained by other sub-teams.
TechDocs includes members of the Technical Advisory Council, as well as members of the ArchivesSpace Program Team. Meetings are also open to Lyrasis developers who support ArchivesSpace.
The Vice-Lead is responsible for taking notes during the meeting and covering for the Lead if they are unavailable. The Lead is responsible for orienting new members, facilitating access to the GitHub repository and Slack channel, scheduling meetings, creating agendas, and writing the quarterly reports on sub-team activities. Both the Lead and Vice-Lead write and submit the retrospective at the end of each term.
In addition to communicating asynchronously via the TechDocs Jira Board and emails, members of Techdocs and the ArchivesSpace program team can use the Slack channel.
The primary source of technical documentation for ArchivesSpace is the archivesspace/tech-docs Github repository (tech-docs repo). A public, more user-friendly version of the content is available at https://archivesspace.github.io/tech-docs/.
The technical documentation is openly accessible and does not require ArchivesSpace membership, in contrast to the User Manual available through the ArchivesSpace Help Center. The two sets of documentation were created and are maintained in different environments due to this difference in access, as well as their different audiences.
All TechDocs sub-team members should have write permissions to the tech-docs repository and assigned to the archivesspace/tech-docs team. Before the beginning of each term, the sub-team lead should email Christine DiBella with the Github handles of the sub-team members to facilitate access.
Select the menu icon in the upper left-hand corner, and select archivesspace/tech-docs under the “Teams” section:
2. Select the green “Add member” button.
3. Type ahead for the person’s GitHub username. Only people already added to the archivesspace team in GitHub can be added here. Email Christine if anyone is not already a member of that team.
4. Subteam members are encouraged to enable notifications from the repository via the Watch functionality.
5. Subteam members responsible for overall repository maintenance (i.e., subteam Leads and Vice Leads) should be assigned to the “Maintainer” level role. Within the techdocs Team page, select the user(s) with the checkbox, click the “1 member selected” icon, and “Change role.”
In the context of Git repositories, a pull request is an event where a contributor asks the repository’s maintainer to review changes on an independent line of development that they want to merge into the main branch.
Pull requests to the repository should be reviewed and merged promptly.
Straightforward pull requests with no conflicts should be merged by the subteam Lead, or delegated to other TAC members if needed.
Pull requests with branch conflicts or content that warrants review by a developer can be identified by the Lead for a program developer to merge.
Draft pull requests cannot be merged, and can remain in the repository.
Navigate to the techdocs repository.
Select “Pull requests.”
3. From the list of requests, select the specific pull request to merge.
4. Merge the commit(s) into the base branch by selecting “Merge pull request” (if this option is not shown, select “Create a merge commit” from the drop down menu)
5. If prompted, type a commit message.
6. Select “Confirm merge.”
