Trip report: Write the Docs Portland 2017

[Janet Swisher]

Earlier this week, I attended the Write the Docs conference[1] in
Portland, Oregon. Here are some notes from that experience:

* I was glad that I did not go on the pre-conference hike on Saturday,
after I heard that those who went got caught in a hailstorm.
* The MDN table at the Writing Day on Sunday was very successful.
There were about 10 participants, and we had to pull 2 tables
together. I asked participants to help us with converting CSS
reference pages to "examples on top" structure. I had a list of 100
pages, ranked by traffic, provided by Will. The group finished that
list by lunch time. After that, I told people to just pick pages
from the CSS reference index page, and add them to the spreadsheet
we were using for tracking. About 160 pages were updated, in total.
I thanked participants by sending them Happiness Packets[2].
* Kate Voss's presentation about error messages[3] gave me the idea to
link from our HTTP error response pages to the HTTP response code
docs[4].
* Tom Johnson's talk on design principles for building navigation[5]
mentioned some things we're already doing, and others to consider,
like making it easy to access the most popular topics.
* Lyzi Diamond gave a talk about automated doc testing; her tool might
be relevant for Anthony's work on the MDN doc tester add-on. (I'll
try to get links.)
* Christie Lutz gave a talk on using design critique guidelines to
improve getting and giving feedback. For example, use a scope
statement when requesting feedback: "I am sharing [early/mid/late]
work, around [the problem or problems], because [why it's a
problem]. And I am looking for feedback around [specific focus for
feedback]. At this time, I don't need [areas outside the scope of
this review]."
* Ryan Pitts and Lindsay Muscato from OpenNews described their
experience putting on a doc sprint, without mentioning MDN at all ;-)
* I went to an unconference session about making videos for developer
audiences. Consensus in the session was to keep videos as short as
possible. The group included a developer who said she hates videos.
She suggested that if a video has no audio, clearly label that fact;
that way, she'll know she doesn't have to turn off her music to
watch it, and might be slightly more inclined to do so.
* I led an unconference session on combining "agile" methods and
openness. Other open source projects do not seem to have the issues
that our team does with this. Most use bug trackers to make
tasks-to-be-done open and "takeable" by volunteer contributors. The
WikiMedia Foundation uses their "Technical Collaboration
Guidance"[6] to ensure community involvement in large-scale
planning. I'm going to be following up with folks from WMF for more
knowledge-sharing about how they manage their processes. I have
plenty more feedback from this session that I'm still digesting.

Videos of the main track talks will be available in 2-3 weeks.

If you'd like to present at Write the Docs in Prague in September, get
your proposal ready! The CFP closes May 31st![7]. There is also interest
in creating a Write the Docs conference in Latin America; if you'd like
to help with that, let me know, and I'll connect you with the right people.

[1] http://www.writethedocs.org/conf/na/2017/
[2] https://happinesspackets.io/
[3]
https://docs.google.com/presentation/d/1gCgkaaXIFSLf3afRxEGNFwm0bPTcURcVQNuQj0QZDqQ/edit?usp=sharing
[4] https://bugzilla.mozilla.org/show_bug.cgi?id=1366376
[5] http://idratherbewriting.com/files/doc-navigation-wtd/index.html#/
[6] https://www.mediawiki.org/wiki/Technical_Collaboration_Guidance
[7] http://www.writethedocs.org/conf/eu/2017/cfp/

--

Janet Swisher <mailto:jREMOVE...@mozilla.com>
Mozilla Developer Network <https://developer.mozilla.org>
Community Strategist

[William Bamberg]

On Fri, May 19, 2017 at 2:08 PM, Janet Swisher <jswi...@mozilla.com> wrote:

> Earlier this week, I attended the Write the Docs conference[1] in
> Portland, Oregon. Here are some notes from that experience:
>
> * I was glad that I did not go on the pre-conference hike on Saturday,
> after I heard that those who went got caught in a hailstorm.
> * The MDN table at the Writing Day on Sunday was very successful.
> There were about 10 participants, and we had to pull 2 tables
> together. I asked participants to help us with converting CSS
> reference pages to "examples on top" structure. I had a list of 100
> pages, ranked by traffic, provided by Will. The group finished that
> list by lunch time. After that, I told people to just pick pages
> from the CSS reference index page, and add them to the spreadsheet
> we were using for tracking. About 160 pages were updated, in total.
> I thanked participants by sending them Happiness Packets[2].
>

This was really amazing. I wondered if there's a way we can thank these
people publicly, using some 'official' Mozilla channel, like @MozDevNet.

> * Kate Voss's presentation about error messages[3] gave me the idea to
> link from our HTTP error response pages to the HTTP response code
> docs[4].
> * Tom Johnson's talk on design principles for building navigation[5]
> mentioned some things we're already doing, and others to consider,
> like making it easy to access the most popular topics.
> * Lyzi Diamond gave a talk about automated doc testing; her tool might
> be relevant for Anthony's work on the MDN doc tester add-on. (I'll
> try to get links.)
> * Christie Lutz gave a talk on using design critique guidelines to
> improve getting and giving feedback. For example, use a scope
> statement when requesting feedback: "I am sharing [early/mid/late]
> work, around [the problem or problems], because [why it's a
> problem]. And I am looking for feedback around [specific focus for
> feedback]. At this time, I don't need [areas outside the scope of
> this review]."
> * Ryan Pitts and Lindsay Muscato from OpenNews described their
> experience putting on a doc sprint, without mentioning MDN at all ;-)
> * I went to an unconference session about making videos for developer
> audiences. Consensus in the session was to keep videos as short as
> possible.

Exactly my opinion!

> The group included a developer who said she hates videos.
> She suggested that if a video has no audio, clearly label that fact;
> that way, she'll know she doesn't have to turn off her music to
> watch it, and might be slightly more inclined to do so.
>

That's an interesting suggestion.

> _______________________________________________
> mdn mailing list
> m...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/mdn
>

[Janet Swisher]

On 5/19/17 17:08, Janet Swisher wrote:
>
> Earlier this week, I attended the Write the Docs conference[1] in
> Portland, Oregon. Here are some notes from that experience:
>

> * Lyzi Diamond gave a talk about automated doc testing; her tool
> might be relevant for Anthony's work on the MDN doc tester add-on.
> (I'll try to get links.)
>

Here's the tool that Lyzi was talking about:
https://github.com/katydecorah/copy-cop

[Kadir Topal]

This is a great write up. Thanks Janet!

> Am 19.05.2017 um 23:38 schrieb William Bamberg <wbam...@mozilla.com>:

>
> On Fri, May 19, 2017 at 2:08 PM, Janet Swisher <jswi...@mozilla.com> wrote:
>
>> Earlier this week, I attended the Write the Docs conference[1] in
>> Portland, Oregon. Here are some notes from that experience:
>>

>> * I was glad that I did not go on the pre-conference hike on Saturday,
>> after I heard that those who went got caught in a hailstorm.
>> * The MDN table at the Writing Day on Sunday was very successful.
>> There were about 10 participants, and we had to pull 2 tables
>> together. I asked participants to help us with converting CSS
>> reference pages to "examples on top" structure. I had a list of 100
>> pages, ranked by traffic, provided by Will. The group finished that
>> list by lunch time. After that, I told people to just pick pages
>> from the CSS reference index page, and add them to the spreadsheet
>> we were using for tracking. About 160 pages were updated, in total.
>> I thanked participants by sending them Happiness Packets[2].
>>
>
>
> This was really amazing. I wondered if there's a way we can thank these
> people publicly, using some 'official' Mozilla channel, like @MozDevNet.

Yeah, thanks so much for organizing this Janet! I was wondering: Did you get any feedback from these first time users about ease of signing up, editing or publishing? Did you notice anything when you watched them edit?

> * Kate Voss's presentation about error messages[3] gave me the idea to
>> link from our HTTP error response pages to the HTTP response code
>> docs[4].
>> * Tom Johnson's talk on design principles for building navigation[5]
>> mentioned some things we're already doing, and others to consider,
>> like making it easy to access the most popular topics.

>> * Lyzi Diamond gave a talk about automated doc testing; her tool might
>> be relevant for Anthony's work on the MDN doc tester add-on. (I'll
>> try to get links.)

>> --
>>
>> Janet Swisher <mailto:jREMOVE...@mozilla.com>
>> Mozilla Developer Network <https://developer.mozilla.org>
>> Community Strategist
>>

[Janet Swisher]

On 5/29/17 08:27, Kadir Topal wrote:
> This is a great write up. Thanks Janet!
>
>> Am 19.05.2017 um 23:38 schrieb William Bamberg <wbam...@mozilla.com>:
>>
>> On Fri, May 19, 2017 at 2:08 PM, Janet Swisher <jswi...@mozilla.com> wrote:
>>
>>> Earlier this week, I attended the Write the Docs conference[1] in
>>> Portland, Oregon. Here are some notes from that experience:
>>>

>>> * The MDN table at the Writing Day on Sunday was very successful.
>>> There were about 10 participants, and we had to pull 2 tables
>>> together. I asked participants to help us with converting CSS
>>> reference pages to "examples on top" structure. I had a list of 100
>>> pages, ranked by traffic, provided by Will. The group finished that
>>> list by lunch time. After that, I told people to just pick pages
>>> from the CSS reference index page, and add them to the spreadsheet
>>> we were using for tracking. About 160 pages were updated, in total.
>>> I thanked participants by sending them Happiness Packets[2].
>>>
>> This was really amazing. I wondered if there's a way we can thank these
>> people publicly, using some 'official' Mozilla channel, like @MozDevNet.
>
> Yeah, thanks so much for organizing this Janet! I was wondering: Did you get any feedback from these first time users about ease of signing up, editing or publishing? Did you notice anything when you watched them edit?

Nobody complained about the sign-up process. I was busy answering
questions about the task at hand and forgot to watch people sign up or
sign in. There were a couple of people who had old Persona-based
accounts that they hadn't updated to Github, and couldn't log in. They
were both OK with just creating a new accounts, since I didn't have
anyone on call to help enable their old accounts. I discovered after the
fact that one person ran into the spam trap, and went away without
saying anything about it. I sent him an email apologizing and inviting
him to return, but never heard back.