Documentation team mission

To organize and improve ArchivesSpace technical documentation, to decrease the risk that missing or misleading documentation will impede development and implementation.

Current Documentation areas:

• http://docs.archivesspace.org (members only) [user, which isn’t within TAC purview]

• http://github.com/archivesspace/archivesspace (~25 readmes)

• http://stackoverflow.com/questions/2304863/how-to-write-a-good-readme

• http://github.com/archivesspace/archivesspace/wiki

• http://archivesspace.github.io/archivesspace/doc/ 

• Pivotal tracker: https://www.pivotaltracker.com/s/projects/386247

• Committer Oversight have included this in the contribution guidelines

• Basecamp writeboards (https://archivesspace.basecamphq.com ? need access)

• I have been told these are mostly of historical interest only (which has a place but should be so noted).

• ArchivesSpace youtube videos made by HudsonMolongo here => http://www.youtube.com/playlist?list=PLJFitFaE9AY_DDlhl3Kq_vFeX27F1yt6I

• Also, Mark Triggs from HudMol wrote a blog post about writing a plugin, which is pretty good => http://teaspoon-consulting.com/articles/archivesspace-plugins.html

• Fitz shared: http://ericholscher.com/blog/2014/feb/27/how-i-judge-documentation-quality/

• the current github.io stuff looks like it was done with YARD, which does generation from source (though you can also have the documentation (in the repository but) outside the source code that this guy is talking about)

• draft contributing guidelines

Suggested documentation team tasks:

• Determine relationship with other subgroups’ documentation tasks

• Committer Oversight: *new* developer documentation, documenting the to-be-established workflow for PRs, code reviews, &c.

• Migration: migration documentation, which may end up being considered (advanced) user documentation

• Architecture: is looking over all the code -- still needs identified

• Determine where documentation should live

• Review quality of current documentation, suggest areas of improvement

• Review ASpace-team generated documentation for clarity, completeness, etc

• Develop guidelines and templates for documentation of code contributions

• what tool(s) to produce documentation

• coordinate with Committer Oversight, who have something similar in their work plan

• Follow user group lists, develop knowledge base from questions that arise

• UAC’s documentation group intends to pass technical things on, but we should also be monitoring, in particular to identify areas where technical documentation could be improved

• Also create list of what types of documentation are needed, which group should have ownership

Goal: first review by next call

What goes in the READMEs v. documentation website?