Documentation Workflows for Digital Security Education and Rapid Response
|Documentation Workflows for Digital Security Education and Rapid Response|
|Presenter(s)||Jon Camfield, Noah Swartz, Chris Walker, Wojtek Bogusz, Maya Richman, Jun Matsushita, Floriana Pagano, Ali Ravi, Sanne Stevens, Holly Kilroy, Michael Carbone, Rory Byrne, Kaustubh Srikanth|
|Organization(s)||Internews, EFF, Tactical Tech, Frontline Defenders, The Engine Room, iilab, Equalit.ie, Confabium, DDP, Rapid Response Coordination Centre, Access Now, Security First|
|Project(s)||DFAK, SAFETAG, SSD, SiaB, Level Up, Orgsec.Community, Umbrella, contentascode, Helpline community documentation|
|Country(ies)||US, Germany, UK, Poland, Canada, The Netherlands|
|2017 theme||Training & Best Practices|
Friday March 10 9:45am-1:15pm at New Room
This 3 hour session begins with a 1.5/2hr workflow share for documentation efforts: what has worked? What hasn’t? Do we have common success/failure stories? How can we smooth the path for groups that desire to make more public documentation?
We seek to draw experience from creators, maintainers, localization managers and users of various documentation efforts for different communities such as:
- rapid response: Digital First Aid Kit, Digital Security Helpline community documentation
- trainers: Level Up
- org auditors/implementers: orgsec.community, SAFETAG
- end-user documentation: Security-in-a-Box, Surveillance Self-Defense, Umbrella
- meta-efforts: OpenMentoring, contentascode
The session hopes to foster a dialogue between documentation writers to help us create and implement best practices and workflows for the future, to improve our collective knowledge and best educate our audiences.
After gathering best practices to approach documentation efforts, for the remaining 1/1.5hr of the session participants will split into groups to apply these best practices on existing documentation needs, including:
- training materials for rapid responders
- training guide for internal org infrastructure
- org policies templates
- workflows for sharing suspicious emails, devices, URLs, files
|Target Groups||Security Trainers, Designers Usability, Communications Professionals|
using git more effectively in the editing workflow ;
how external contributors
tooling for non-techies to use git
better terminology; getting beyond branch/blame "gitsplaining"
examples of editing tools/systems: from contrib
- atom with gitplugin
- iilab's content as code work
TLDR: markdown to git works well, but complex process, we need to simplify the workflow from the contribution and content mgmt flow
also tracking posterity with decisions and commit/pull/issue/comment
and translation... transifex options for workflow implementation
- middle and output
subblock metadata enabling including piewces of content in other content, eg pulling in a section from one, a complete file from another, and a subsection of a third
Static Site Generators can do this with includes, headers, and footers, but not a solved problem with core content pieces
SAFETAG currently uses markdown; a markdown pre-processor, pandoc, stylesheets, and wkhtmltopdf to build an html file and PDFs from them
- Output needs
what does this mean for documentation?
2 different types of community: beneficiaries and content writers/editors -- some projects, could be very different, can sometimes be the same community
what are the spaces and action sthat organize the community?
- support / resources
different forms of receiving feedback
- email / black box process
- better to invite ppl, creating a space for feedback that's more proactive -- drop the feedback into the space
* concern that this still is a drop-off process, not community building * maybe push this feedback back into a community by subscribing ppl to the content section and its updates; * create an "echo" to keep a discussion / informed community
- Effect way of creating community through physical meetings, but those are difficult
- Good idea to have mtgs like this remotely -- but won't happen w/o a community lead
- but big value in creating this space, flexible space, could offer -- training/support work
People who are revisiting matierals are trainers, also they see the impact oif the doc with the beneficiary ("USABLE for documentation")
Other prob with email is that there is no cross-community engagement, only 1:1 upstream -- peer communication (and support?) useful?
Aspiration Tech has a "contributing trainers" doc emailing list? open list
- Localization / Translation
glossaries - if there is no word, how do you translate?
There are created glossaries (where are these?)
mix of actual usage, invented new terms, media usage, and sometimes standardization bodies (but might be too formal)
eq labs, tails, accessnow are doing translation
gender and language
amount of text to localize, and which tools are useful here -- markdown/transifex
gdocs and realtime contribution
challenging to specify very tightly where to change a translation
Known Gaps and Requirements and Needs oh my!
- NEED: Tooling to automate git+markfdown/transifex
* Yes but transifex requires pull access * Requires some formatting standardization * Tails: gens po files from source code using PO4A that merges partially/existing translated documents to bootstrap * SSGs lack translation PO file plugin; perhaps we must deal with this outside the SSG work
Summary need: 2-way git/PO workflow
- NEED: List of SSGs; other tooling infrastructure for write-git-review workfloy
what is the continuous integration wrokflow what are the review processes and checklists (internationalized, localized, what is the doc testing protocol)
- Maya knows a list of SSGs: staticgen.com
- Jekyll; Metalsmith?
- Content as Code also has some options
- gitlab, github, gitlab.com
problem: interactive things commenting, sitesearch?
- NEED: non-tech contributors in markdown workflow
- Atom with git
- plus solid training to express the git magic words in normal editing workflow , git workflow is horribly obfuscated
- Prose is probably not good for large-scale, but worth noting
- git* web interfaces allow some preview/live editing -- web interfaces may be a requirement
- NEED: How do we as a documentation community share best practices, document documentation, and continue our work?
- Is there an existing place where people gather?
* orgsec.community? contentascode? discourse? gitlab/hub to use issues-as-discussion * Jun to host a rocket.chat or mattermost? * Please something with email and chat and stuff
There is an IFF mattermost channel, @houndbee / kaustubh@ttc will follow up with Jun and others to create something better. Mic hael wants it pushed to email.
WHO DOCUMENTS THE DOCUMENTERS
- NEED: Localization presentation standardization
- making this work the same at some level
- standardized info architecuture/metadata?
- establish a norm: translation: all in the same folder: resource.lang.ext
- NEED: De-duping atomized documents
- e.g. having one guide for a tool, and have that at the tool, built with the tool, and linked across!
- NEED: Better output / exploration interface
- Better build workflows to avoid indesign lockin
- We need to build a list of current approaches!
* Seamus' Document-Builder to string markdown preprocessing; pandoc, PDF printing and CSS underpinning with pandoc and wkhtmltopdf which leverages CSS to solve some problems * Tom has as process as well * SIAB also uses pandoc * is web to pdf the best path, or do we template in LaTeX? -- easier CI workflow than htmlcss->pdf * Depends on the frequency of content vs design changes and # of design targets (books, web, booklets, apps, mobile...?) -- monthly or annually has big different pain points * cryptoparty - CI with pandoc with html/pdf/ via github.com/cryptoparty/handbook
- SIAB pipeline uses pandoc for html and pdf; there is overall a dependency problem
- Resources to do this with?
Let's fill this out with
Project, url, host/owner,
- TTC: SIAB?
- accessnow's whatever *.* doc community, policy
- CPJ ojurnosec guice
- Community research
- Jun in spirit
- TTC: Myshadow/train?
- TTC: gendersec?
- TTCExposing the invisible
- SecurityFirst: Tent, Umbrella
- Fabriders anonymous resource project
- localization lab
- webly and trasifex, poodle devs