LSST Data Management uses a number of technical communication and documentation platforms to address our needs, with the SQuaRE team often leading the management (and development, when necessary) of these platforms. Each platform addresses a specific niche of audience (DM, Project or our science community), synchronicity (real-time, asynchronous, or broadcast), and task (e.g., work ticketing, documenting designs, manuals).
This technical note outlines the platforms that DM uses to communicate and document our work. It also describes new platforms we are building to improve communications and documentation, and how these platforms might roll into LSST operations.
In particular, this document introduces an information architecture where two platforms—this Community forum, and an up-coming DocHub documentation index—are designated as information entry points that can be used by DM internally and the science community at large. This architecture will solve the oft-cited problem of information discovery given the fact that information naturally lives on different platforms given context.
We welcome your thoughts and feedback on this technote and the overall DM communications strategy in this thread.
The following are slides that accompany and summarize this technical note:
Based on recent discussions surrounding ad-hoc platforms being used to facilitate specific work, I want to specifically highlight this paragraph from SQR-011 on Draft document collaboration:
Teams and ad-hoc working groups often use standard commercial services such as Google Docs, Google Spreadsheets and Dropbox as ways of working on drafts of documents, spreadsheets, presentations, etc… We are happy for people to use whatever tools make them productive in early stages of their thinking.
Documents on ad-hoc platforms are not expected to be discoverable in any automated sense. Users of these platforms should take care to personally invite any relevant colleagues to collaborate on these platforms. Once the document has matured (and if it is not evanescent) we expect it will find its way to one of the official documentation platforms, and be announced on the DM Notifications forum category.
We would like to see some centralised project support to extend popularly used collaboration services such as Dropbox to the whole team, instead of having people use their personal accounts for this.
The question in my mind is whether allowing people to use “whatever tools make them productive” provides greater benefits than standardizing tools even at the document drafting stage. The potential advantages of the latter include:
To make the discussion concrete, it might be useful for us to list the collaborative activities that happen outside of our normal JIRA workflow and HipChat/Community conversations, and propose suggested workflow patterns for DM. I can think of:
Collecting research before writing a paper or design document (the paper itself can probably be handled in the usual JIRA/GitHub collaborative workflow.
We’re using a GitHub wiki for the Astropy integration paper. Would people feel better if this was in a Confluence wiki instead? I.e., Confluence, and the Data Management space in particular, is the one and only place where draft pages meant to be collaboratively produced should occur?
Discussing a paper being drafted.
While the astropy integration paper is being written, there are thoughts to offer input to the paper in GitHub issues; should all of this happen on Community instead?
I can imagine a system where we formally give each paper/design document its own Community tag. Then the README for the paper would say “Discuss this paper on Community in using the xyz tag.”
GitHub Pull Requests would then be used more for editing the text itself rather than discussing/debating larger ideas.
Making a presentation.
In this case I think having an official Dropbox workflow for DM would be appropriate (although I personally prefer passing around PDFs of presentations rather than the source document itself to prevent compatibility issues). When we have Slack, I could see us setting up Channels to iterate on presentations by sharing PDF versions.
What are the other communication edge cases?
I consider meeting notes to be a solved problem: personal or Google Doc note files compiled during the event should be edited and posted to the LSST Project category on Community (or Data Management if there is no sensitive information; use the conference-report tag in either case).
I used the GitHub wiki because there were going to be lots of little pages and it uses git. It was also done with the intention of it being deleted once we were done. There was also the added bonus that it was easy to give external Astropy people write access when they wanted to contribute. It may be that external collaborations are a special case and most of the time this won’t be happening.
I don’t mind community being used for that. I worry that we don’t have an easy scheme for people to filter specific tagged topics out of their message stream.
A Dropbox link to the PDF is fine. It just has to end up somewhere that is not Dropbox when it’s done.