8/25/2014 call notes
Notes from 8/25/14 TAC Documentation group call
Chris Ervin
Brad
Kari
Sybil
Chris Fitz
Laura
[Terry unable to attend]
Background from Brad on what the User documentation group is doing.
TAC meeting at SAA - documents group user documentation and training
- there was the potential for duplication of work and we wanted to coordinate better
- 2 day workshop workbook that was done was better than the user documentation currently available
- outcome of the meeting: Workbook would become the manual (screen shots, linking tasks to archival practice)
- Decision to move documentation out of MadCap Flare (a proprietary system); move to something that would allow more involvement in the editing process, e.g. Sphinx
Looking at the goals developed by Chris (from Aug 4th document)
Documentation Subgroup
Formulate process in which documentation creation is in sync with development & release cycle
Assess current document practices and propose recommendations. I think we all agree having the technical documention in Github is the best way, but do we need organize this in a better way or possibly publish these on another site as put of a Git post commit hook ( such as https://readthedocs.org/ or our own github pages site?)x`x
Identify holes, unclear, or out-of-date documentation. Establish a process of making these changes and begin the process.
Establish a process in which common questions/answers on the email list get captured.
Possibly collaborate with Committers group to unify the developers documentation, API documentation into a single format.
Formalize general practices as to what go where. For example, what gets a README in github, what goes into the github wiki, what should go into confluence wiki, etc.
Establish a list of good tutorial proposals.
Comments:
Communications plan:
Identify avenues for getting the technical documentation out, e.g.every so often (monthly, etc.) post out a feature, link to a tutorial, etc.
Suggest and comment on topics that Chris can write up before sending it out. Also to alert Chris about doing this …
Establish a place to put links and things that turn up on the Hudson Molongo blogs.
Take a look at “readthedocs.org” site (Chris mentioned from other projects) to see if it would be good for us to move to.
http://ubuntu-cloud-installer.readthedocs.org/en/latest/
http://pypy.readthedocs.org/en/latest/
Existing Group’s goals
Documentation of suggestions of wiki reorganization - how do we get this to Chris for review of content? Decision that the TAC documentation group would edit the wiki. In terms of reorganizing the content - suggestion to get the entire TAC groups feedback on the usability of the organization of the documentation.
Email: group.
we send items (from Laura’s list of what to reorg) to Chris for content based review
Chris (or someone equally wise) would need to do the “Merge into README_TOMCAT” item
we take Chris’s edited content, get write access, and edit the wiki and reorganize the content
share with TAC group for looking over the reorg for feedback
We need to ask Committer Oversight if their content (“Contributing”) is ready to be used on the wiki for the items under “Project process documentation.”
Noting that the first time through would be more of Chris’s time and effort than future adjustments.
One person from TAC documentation, once a month, take the info from the listserv (archivesspace Google group and the archivesspace user group list)
Then review the existing documentation, or when it will be created
Also, when the info feeds into tutorial proposals, also note those (addressing Chris’ last bullet item)
Coordinate who is doing this with Chris so he can also send along messages he gets from alternate sources.
Next Steps
Kari will send out Action Items resulting from this call.
Consider using a single documentation system (User and Technical)
what are the implications for access control (user docs only for membership?)
Lyrasis is looking what might replace madcap flair for documentation.