Documentation Workflows for Digital Security Education and Rapid Response

From IFF Wiki
Jump to: navigation, search
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,, 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
Social media
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:, 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

Format Workshop
Target Groups Security Trainers, Designers Usability, Communications Professionals
Length 3 hours
Skill Level Advanced
Language English

Session Outputs

Next Steps

Additional Notes

Relevant Resources


  1. INPUT

using git more effectively in the editing workflow ;

how external contributors

demystify git

tooling for non-techies to use git

better terminology; getting beyond branch/blame "gitsplaining"

examples of editing tools/systems: from contrib

  • atom with gitplugin
  • prose
  • 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

  1. middle and output
    1. transmark

extends markdown

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

    1. SAFETAG

SAFETAG currently uses markdown; a markdown pre-processor, pandoc, stylesheets, and wkhtmltopdf to build an html file and PDFs from them

    1. Output needs

Faceted search

  1. Community

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?

  • feedback
  • 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

  1. 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

computer-assisted translation?

Known Gaps and Requirements and Needs oh my!

    1. 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

    1. 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:
  • Jekyll; Metalsmith?
  • Content as Code also has some options
  • gitlab, github,

problem: interactive things commenting, sitesearch?

    1. 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
    1. 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?
 * contentascode? discourse? gitlab/hub to use issues-as-discussion
 * Jun to host a 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.


    1. 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
    1. 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!
    1. 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

  • SIAB pipeline uses pandoc for html and pdf; there is overall a dependency problem

    1. Resources to do this with?

Let's fill this out with

Project, url, host/owner,

  • Levelup
  • TTC: SIAB?
  • Totem
  • accessnow's whatever *.* doc community, policy
  • CPJ ojurnosec guice
  • SSD
  • Community research
  • Cryptoparty
  • Jun in spirit
  • TTC: Myshadow/train?
  • TTC: gendersec?
  • TTCExposing the invisible
  • SecurityFirst: Tent, Umbrella
  • CRJ?
  • APC
  • ASL19?
  • Fabriders anonymous resource project
  • DFAK
  • localization lab
  • webly and trasifex, poodle devs
  • ReadtheDocs/Writethedocs


  • Tor
  • GlobalLeaks
  • Qubes
  • SecureDrop
  • fdroid
  • veracrypt