Call for help on documentation


#1

@conorsch @redshiftzero

We have around 40 issues on docs and after looking at them it indeed looks like a good starting point to ask for help. The blocker is, maybe, the need to learn about SecureDrop before being able to work on most issues. But it’s difficult to presume.

What about we send a call for help with

  • the docs issues URL
  • a pointer to the getting started section in which we need to add a link to the style guide + a link to a guide about creating a pull request
  • explain that being blocked by something (anything) is a valuable contribution that should materialize into a new issue

I’d be happy to draft something along these (to be proofreaded by a native english speaker ;-). And then we could spread it to an audience likely to attract less than 10 contributors but more than 5. There is a good chance they will be blocked by various things that are difficult to effectively anticipate so we don’t want to attract too many people :wink:

What do you think ?


#2

The plan sounds great! What form do you expect the actual outreach to take? We have the “securedrop” Twitter account, which should be used more for encouraging contributions than we’d managed to date. A tweet would only be a short blurb, so it’d need to link out to a longer guide, similar to @redshiftzero’s hackathon guide: https://gist.github.com/redshiftzero/81779c42b66738c9478e0f8b830f337f

Then pointing everyone to that resource is a great start. Perhaps we should finally start to use the GitHub “wiki” feature to maintain support docs of this nature. Wouldn’t be opposed to linking directly to a Discourse thread, either.


#3

I’ve had good experiences in the past with real short call for help on a specific topic. For instance something like:

We’re looking for help to improve the SecureDrop documentation! If you have an hour to spare or more, just pick an issue at https://github.com/freedomofpress/securedrop/issues?q=is%3Aissue+is%3Aopen+label%3Adocs . The contributor guide helps figure out the details https://docs.securedrop.org/en/latest/development/getting_started.html#writers

I don’t feel strongly about this and there is a good chance your ideas are better than mine :wink:


#4

Sorry, by “form” I meant “Tweet, or otherwise?” I’m fine with Twitter, seems the best way to accomplish outreach given that calls on GitHub will only be seen by folks already contributing.


#5

I don’t really have an opinion on that. I was not even aware that it was possible to broadcast something on GitHub :wink:


#6

This is a bit further down the line, but if we write up a really great documentation GitHub gist, we could make use of it as part of SD hackathons, and have a smaller “editathon” with it.


#7

https://twitter.com/SecureDrop/status/949051731408666624 thanks @redshiftzero !


#8

Thanks to @dachary for preparing the tagged issues and linking them in the getting started section of our documentation! Let’s monitor how this goes and we can tweet additional calls as we see fit.


#9

#10

It has been over a week since the call for help and

pierwill was active on documentation issues and sent pull requests, but they were already contributing before the call for help. The other documentation contributors in the past week are also not new contributors.

I think we can conclude this call for help did not work and try to fix this.


#11

Maybe (just maybe :wink: a few contributors clicked on the provided link, browsed the docs issues and did not find something suitable. I browsed all 49 open issues asking myself: As a new volunteer with experience as a technical writer and fluent in English, what issue can I try to fix within the hour ? But I did not find any. There are a few which may be a good fit such as two-factor unification, but only if the person is already very familiar with two-factor authentication terminology which is unlikely. And the language used in the issue description is not authoritative (it does not say must but should) and suggest the first step is to engage a dialog to establish a consensus on which term to use. It may not take very long but is not timeboxed either.

What about we do the following:

And then we can send another call for help and see if we get better results


#12

Fun fact: minutes after the new easy documentation issue was filled, someone proposed a pull request. Intrigued by the coincidence I asked how that happened and it turns out this is via the GitHub global search, looking for recent issues with the easy label.


#13

I’m going to create some easy documentation tasks then. And add a link in the documentation.


#14

@redshiftzero would you mind sending another call for help on documentation, focusing on easy documentation tasks ? This is an kind of scientific experiment and our goal is to figure out if such a call for help reaches at least one contributor. We know these bugs are solvable and attractive to new contributors (thanks to the first spontaneous fix). If nobody fixes any of the three existing bugs within a week after the call, we can conclude this is not the right channel to reach contributors.

What do you think ?


#15

@redshiftzero ping ?


#16

Tweeted out all our easy issues: https://twitter.com/SecureDrop/status/960601713777418240

Let’s see how this goes :slight_smile:


#17

A person who contributed in the past saw the call and proposed a documentation PR https://github.com/freedomofpress/securedrop/pull/2977 :tada:


#18

All the easy doc bugs were fixed and this is good :slight_smile: But I think it does not count for our little experiment because, a) one of them was fixed by a former contributor, b) two were fixed by a GSoC applicant. As a conclusion it looks like the SecureDrop twitter account does not reach potential new contributors. We know the docs bugs are not a blocker, they really are easy and first time contributors had no trouble fixing them.

Is there a way to reach a larger or more targeted audience ?