Tech Docs Workplan for 2017-2018

Owned by Scott Hanrath (Unlicensed)
Last updated: Dec 14, 2017


1. Enhance provisioning documentation

Rachel Maderik (Unlicensed), Trevor Thornton, Bobbi Fox (Unlicensed)

  • The current documentation regarding enabling HTTPS does not contain adequate detail for configuring the ArchivesSpace application, but rather serves more as a general introduction to setting up SSL with Apache. The ideal documentation would contain explicit instructions on which lines to modify in the ArchivesSpace config.rb file, as well as what may need to be modified in the server configuration dependent on environment (Windows, Linux, OS X) and web server (Apache, Nginx).
  • Need more documentation on external Solr server support.

2. Enhance plugin documentation

Dallas Pillen, Bobbi Fox (Unlicensed)

E.g., getting started with plugins, general plugin setup and configuration, what can plugins do

Potential to work with plugin portal/directory

Some potential areas of documentation:

  • What can be overridden by replacement in the plugin's directory (e.g., .erbs in views/) and what can't (e.g. .rbs in controllers)
    • and what to do about overriding behavior in the latter (e.g.: using Foo.module_eval do in the plugin_init.rb to add/override functionality)
    • Can routes be overridden, or just concatenated; if the former, how to do it.
    • Can some AppConfig values be overridden, and if so, which ones?
  • Best practices if you expect to have more than one plugin (e.g.: what happens if you have two plugins, each of which need to add a button to the same page?)
  • Writing messages to the log file
  • For the advanced developer, being given a better understanding of when/where the various parts of the plugin get "read into" ArchivesSpace, so that debugging is less fraught. (Example from today: it seems that my frontend/schemas/my_pretty_good_job.rb isn't getting read in; it would be really nice to know where to look!)

3. Make it easier to contribute to tech docs

Trevor Thornton

Moving all ArchivesSpace technical documentation to a single GitHub repository (separate from the repository used for the application codebase) could have several potential benefits. First, consolidating the various sources of technical documentation that are currently hosted on different platforms and in different formats will make it much easier for implementers to find the information they require for configuration, deployment, plugin development, and integration of ArchivesSpace with other systems. Using GitHub as the platform for managing the documentation provides a mechanism for collaborative development and the ability to track changes. The documentation repository could use tagged branches that correspond to application releases, so applicable documentation can be made available for the version of ArchivesSpace that an implementer is currently using. Separating the documentation that currently resides in the main ArchivesSpace GitHub repository will also encourage more input from non-developers who may be intimidated at the prospect of submitting a pull request to the main repo.

Laney McGlohon (Unlicensed) has created a new "just the docs" repo at https://github.com/archivesspace/tech-docs