Doc sprints: The ultimate in collaborative document development

The ultimate in collaborative document development

Doc sprints

1Doc sprints, by Sarah Maddox

People

Time

Documents


What is a doc sprint?

Doc sprints, by Sarah Maddox 3

Setting the sceneA story about our developer documentation

Broken docs

• Too few

• Out of date

• Inconsistent

• Not hitting the spot


Developers do know

Their audience

The subject matter


They don’t know

Where to start

How to write a

tutorial

Whether it’s cool


BookSprints.net7Doc sprints, by Sarah Maddox

BookSprints.net

http://www.booksprints.net

OLPC

http://wiki.laptop.org

FLOSS Manuals

http://flossmanuals.net

Atlassian

http://confluence.atlassian.com/display/DOCSPRINT8Doc sprints, by Sarah Maddox

Early adopters

http://www.booksprints.net/

http://www.booksprints.net/

http://wiki.laptop.org/

http://wiki.laptop.org/

http://flossmanuals.net/

http://flossmanuals.net/

http://confluence.atlassian.com/display/DOCSPRINT

OpenStack

https://wiki.openstack.org/wiki/DocSprint

Mozilla

https://hacks.mozilla.org/?s=doc+sprint

WebPlatform.org

http://www.webplatform.org


More sprinters





http://www.webplatform.org/

http://www.webplatform.org/

The biggest sign of

victory is how many

pages

I managed to delete!



CommunityAnd why people take part

Why do people do it?Developing a new tutorial that hits the spot

Contact between customers and organisation

Learning from experts

Helping people

Fixing stuff



Along with the

immense challenge it

presented personally,

this was also a chance

to work on a product

and a team I’ve never

worked on/with before


Agile or what?Walking and talking agile

15Doc sprints, by Sarah Maddoxhttp://agilemanifesto.org

http://agilemanifesto.org/

http://agilemanifesto.org/

Agile techniques

Timeboxing

Self-organising teams

Efficiency

Structure


Sprints in agile methodologyShort period of development

Shippable product by the end

Planning-meeting at the start

Retrospective at the end



Planning a doc sprintIt’s all about the people

When to start

Initial, 2-3 months

ahead

Full-on, 2 weeks

ahead



Who to invite

Everyone

Developers

Support engineers

Product marketing

Business analysts

CEOs


Who to invite

Community developers

Community authors

Partners

Technical writers

Fans


Who to invite

Make it cool

Use every channel

available

Target individuals

Give plenty of warning

Have some material ready

Remind people


How to invite people

A designer, limited-edition, Atlassian doc sprint T-shirt. No-one else in your

‘hood will have one like it!

Eternal recognition as author. Your name will appear as author of the tutorial

on the Atlassian documentation wiki.

Kudos from the Atlassian technical writers. We’ll write up our results on the

Atlassian blog and you’ll be inducted into the Doc Sprint Hall of Fame.

Learning while you write. We’ll have some Atlassian developers on tap to

help us over the sticky spots. Pair with a technical writer to get those words

buzzing.

Chocolate. Indubitably, there will be chocolate in there somewhere.


The coolth factor

What will you get out of it ?

A designer T-shirt No-one else in your ’hood will have one like it!



Eternal recognition Your name will appear as author of the tutorial on the

Atlassian documentation wiki.



Kudos from usThe Atlassian tech writers will write up our

results on the Atlassian blog and you’ll be

inducted into the Doc Sprint Hall of Fame.27Doc sprints, by Sarah Maddox


Learning We’ll have some Atlassian developers on tap to

help us over the sticky spots. Pair with a

technical writer to get those words buzzing.28Doc sprints, by Sarah Maddox


Chocolate Indubitably, there will be chocolate in there

somewhere.




we may not get

the book we

thought we

would going in,

but by the end

we will get the

book we need

Focus

Wish list

Templates

Style guide

Technical guidelines


Getting the documents you need


Wish list

Collaboration platform

Communication plan

Development environment

Chat, video conferencing, webinars, email

Room and facilities

Catering

Schedule and venue details33Doc sprints, by Sarah Maddox

More planning


Involve people

early

Hot tip


SprintingIt’s still all about the people

Global sprinting

Australia

West, central and east

USA

Russia

Israel

United Kingdom

Germany

Denmark


Different locations

Round-the-clock time zones

English as second language


How to sprint around the world?

Different locations

Round-the-clock time zones

English as second language


How to sprint around the world?

Flexibility

Schedule

Mentorin

g

Technolog

y

Macro tekkie

Early sprinter

Bent rules

Ellis "Alpenmilch"

Pratt

39Doc sprints, by Sarah Maddoxhttp://www.cherryleaf.com

http://www.cherryleaf.com/

http://www.cherryleaf.com/

Remote in Russia

Love for user guides

Tech writer Katya


Alone in Amsterdam

Add-on expert from

aevolu

Travelled from

Büdelsdorf

Andreas "Ritter Sport"

Spall

41Doc sprints, by Sarah Maddoxhttp://aevolu.com

http://aevolu.com/


Sprint schedule

Every day Standup

TeachingDevelopmentFun

Last day

LunchPresentationsRetrospective

First

day

Kick-off

Time Activity

8:00 Tutorial development

9:00 Sprinter meeting and webinar (“standup”)

9:30 Tutorial development

12:00 Catered lunch

13:00 Get your stuff ready for the presentations!

15:00 Presentations and retrospective

17:00 Late webinar with Amsterdam


Example schedule – last sprint day

https://confluence.atlassian.com/display/DOCSPRINT/Schedule+-+Doc+Sprint+August+2012




All in one room or via VC / webinar

Two kick-offs if necessary

Round-the-table

Templates and guidelines

Schedule

Technical environment


Kick-off meeting

Short

What you did yesterday

What you plan to do today

Roadblocks

Further discussions after standup


Daily standup

Documentation techniques

Templates

Source repository

Best practices


Teaching sessions

It’s all about getting the best out of sprinters, and giving them something in

return

Fun and coolth

Theme

Haiku

Weird and wonderful

Lunch and late pizza


"This is the doc sprint

presentations, right?“

"Yes, mate. We're

going to talk about

documentation for the

next two hours. It's

going to be awesome!"


Presentations


Retrospective

What went well

What could have

gone better


Retrospective results

Teamwork

Co-location

Pairing

Organisation

Duration

Doc maintenance

Templates

More teaching

More promotion

More pairing...

What went wellWhat could have

gone better

More pairing


The more

pairing we do,

the greater the

shared learning!


AftermathIt ain’t over until the last doc sings


Review and publication

Decide on tech writer and/or engineer review

Don’t be too picky

Remember the audience

Get it done during the sprint

Blog posts

Tweets

T-shirts

Chocolate

Hall of fame


Thanks and blogs

If you don’t

blog about it,

it didn’t

happen


ToolsEverybody loves them


Collaborative writing

Multiple authors

Ease of use

Notifications

Commenting

Permissions

Confluence

Another wiki

CMS

Booki

Office?

Requirements Tools

HipChat

Tea Party

Google Talk

IRC / Jabber


Chat

Google Groups (?)

Self-compiled mailing list


Mailing list

Webinar versus VC

GoToWebinar

Simultaneously for:

• Kick-off meeting

• Daily standups

• Learning sessions

• Presentations

• Retrospective 59Doc sprints, by Sarah Maddox

Webinar and video conferencing

Bitbucket

GitHub


Code repository


Extending the metaphorKnowing when you’re onto a good thing

Innovation register

A whole day

Funny hats

Presentations

Implementation


Innovation sprints


Doc blitz-tests

Developers

QA engineers

Product managers

Technical writers

And all

Test plan

Kick-off meeting

Collaboration tool

Chat room

Issue tracker

Who What

Team ownership

Team building

Doc verification

Late changes

Bugs in app


Feedback from blitz-test


Doc blitzes

Plan

Collaboration tool

Screenshot tool

Enjoyment

Team spirit

Ownership

Awareness > ideas

Burnout avoided

Preparation Results


More stories and tipsFrom the experts


Knock knock

Around noon on the second day of the First

Book Sprint we hear a knock on the door.

Here is the set up, we're working from a

hotel room in a complex called IMA Design

Village, on the 5th floor of a redeveloped

late 19th Century factory building with a

jerky elevator and nothing to indicate

where we are.

http://en.flossmanuals.net/collaborative-futures/ch046_knock-knock

http://en.flossmanuals.net/collaborative-futures/ch046_knock-knock/

http://en.flossmanuals.net/collaborative-futures/ch046_knock-knock/

1000 edits

400,000 bytes moved

40,000 new words

51 new contributors

57% non-local

4 future doc sprints

68Doc sprints, by Sarah Maddoxhttp://lists.w3.org/Archives/Public/public-webplatform/2013Feb/0120.html

Doc Sprint Dashboard from WPDS

http://lists.w3.org/Archives/Public/public-webplatform/2013Feb/0120.html




Prizes

Food and drink

Cool swag

Just go

SFHTML5 meetup

http://www.sfhtml5.o

rg

/

Running a sprint Taking part

https://twitter.com/peterlubbers

Tips from Peter Lubbers

http://www.sfhtml5.org/






Anti-troll measures deployed

“Oh, you are working on GNOME! I don’t

like GNOME 3, let me troll you.”

... then we got to talking... Face-to-face

interaction win.

Aside from the initial need to deploy anti-

troll measures, it was a successful event.

http://j1m.net/2012/12/28/chicagoans-and-gnome-part-3/





ReferencesThe infamous “for more information...”

Why do people write free documentation? by Andy Oram:

http://

onlamp.com/pub/a/onlamp/2007/06/14/why-do-people-write

-free-documentation-results-of-a-survey.html

Experiencing the Atlassian Doc Sprint - Aug 2012, by

Swapnil Ogale: http://

icreatedocs.blogspot.com.au/2012/09/experiencing-atlassia

n-doc-sprint-aug.html

We Did It: Zero to Book in Five Days, by Anne Gentle:

https://www.openstack.org/blog/2013/03/we-did-it-zero-to-b

ook-in-five-days

/


References 1

http://onlamp.com/pub/a/onlamp/2007/06/14/why-do-people-write-free-documentation-results-of-a-survey.html



http://icreatedocs.blogspot.com.au/2012/09/experiencing-atlassian-doc-sprint-aug.html



https://www.openstack.org/blog/2013/03/we-did-it-zero-to-book-in-five-days/



Atlassian doc sprint wiki:

https://confluence.atlassian.com/display/DOCSPRINT/

How to plan a doc sprint:

http://ffeathers.wordpress.com/2012/09/07/how-to-plan-a-d

oc-sprint

/

A big hairy task list for planning a doc sprint: http

://ffeathers.wordpress.com/2012/09/07/a-big-hairy-task-list-f

or-planning-a-doc-sprint

/

HipChat: https://www.hipchat.com/

Tea Party: http://tea-party.appspot.com/


References 2



http://ffeathers.wordpress.com/2012/09/07/how-to-plan-a-doc-sprint/



http://ffeathers.wordpress.com/2012/09/07/a-big-hairy-task-list-for-planning-a-doc-sprint/




https://www.hipchat.com/

https://www.hipchat.com/

http://tea-party.appspot.com/

http://tea-party.appspot.com/

Google Talk: http://www.google.com/talk/

GoToWebinar: http://www.gotomeeting.com/fec/webinar

Booki: http://flossmanuals.net/booki-user-guide/

Confluence: www.atlassian.com/software/confluence

Bitbucket: https://bitbucket.org/

GitHub: https://github.com/


References 3

http://www.google.com/talk/

http://www.gotomeeting.com/fec/webinar

http://www.gotomeeting.com/fec/webinar

http://flossmanuals.net/booki-user-guide/

http://flossmanuals.net/booki-user-guide/

http://www.atlassian.com/software/confluence

https://bitbucket.org/

https://bitbucket.org/

https://github.com/

https://github.com/

Doc Sprint Mountain View, by Peter Lubbers:

http://blog.webplatform.org/2012/12/doc-sprint-mountain-vi

ew

/

Recap of Web Platform Doc Sprint Berlin, by Andre Jay

Meissner: http://

www.google.com/url?q=http%3A%2F%2Flists.w3.org%2FA

rchives%2FPublic%2Fpublic-webplatform%2F2013Feb%2F

0120.html&sa=D&sntz=1&usg=AFQjCNGDrM5Zap7v4gW

WyT1Xfu_Iu5c_dg


References 4

http://blog.webplatform.org/2012/12/doc-sprint-mountain-view/



http://www.google.com/url?q=http://lists.w3.org/Archives/Public/public-webplatform/2013Feb/0120.html&sa=D&sntz=1&usg=AFQjCNGDrM5Zap7v4gWWyT1Xfu_Iu5c_dg





Innovation sprint:

http://ffeathers.wordpress.com/2010/07/03/technical-writer

s-hold-an-innovation-sprint

/

Documentation blitz-test:

http://ffeathers.wordpress.com/2010/12/04/a-blitz-test-of-th

e-documentation

/

Documentation blitz, by Edwin Dawson: http

://blogs.atlassian.com/2011/09/interviews_from_the_jira_scr

eenshot_doc_blitz

/


References 5

http://ffeathers.wordpress.com/2010/07/03/technical-writers-hold-an-innovation-sprint/



http://ffeathers.wordpress.com/2010/12/04/a-blitz-test-of-the-documentation/



http://blogs.atlassian.com/2011/09/interviews_from_the_jira_screenshot_doc_blitz/




Twitter: @sarahmaddoxhttp://twitter.com/sarahmaddox

SlideShare:

http://www.slideshare.net/sarahmaddox/

LinkedIn:

http://au.linkedin.com/in/sarahmaddox

Blog: http://ffeathers.wordpress.com

Other blog:

http://travellingworm.wordpress.com/


Contacting me

http://twitter.com/sarahmaddox



http://au.linkedin.com/in/sarahmaddox

http://ffeathers.wordpress.com/

http://travellingworm.wordpress.com/

Doc sprints: The ultimate in collaborative document development

Technology

Transcript of Doc sprints: The ultimate in collaborative document development