1 of 45

Documentation Is Getting an Overhaul

Joe Shindelar & Tatiana Ugriumova

2 of 45

Joe Shindelar

@eojthebrave

Tatiana Ugriumova

@tvnweb

3 of 45

What We’re Going to Talk About

What is documentation?
The current state of documentation
What is happening with our tools
Questions we need to solve together

4 of 45

What Is Documentation?

Community documentation (Drupal.org)
API documentation (api.drupal.org)
User Guide (drupal.org/project/user_guide)
External blog posts, videos, podcasts, etc.

5 of 45

Documentation is designed to help move users from one skill level to the next. It gives them the skills they need to build, maintain Drupal site, and Drupal itself.

6 of 45

State of Documentation

Drupal 8 documentation continues to improve
Lots of blog posts, videos, and non-drupal.org content

7 of 45

Pain Points

Lack of curation and review
Versioning
Organization, and findability of content
Translation
External content is often missing dates, version, hard to know if it’s up-to-date

8 of 45

What is happening with our tools?

API documentation (api.drupal.org)
Community documentation on Drupal.org
Drupal 8 User Guide

9 of 45

api.drupal.org

10 of 45

Thank yous

Jennifer Hodgdon
Neil Drumm

11 of 45

Recent Changes

New curated landing page
Syntax highlighting
Works with minor version releases
Updates to work better with Drupal 8
Responsive design
Solr indexing

12 of 45

Community documentation

on Drupal.org

13 of 45

Thank yous

Contributions in the last year

791 people with 2 or more edits
They made 7701 edits

14 of 45

15 of 45

More info: DrupalCon Barcelona presentation, Issue queue

Part of the overall content restructure effort

16 of 45

17 of 45

Introduce the concept of "maintainers" for parts of documentation
Flatten too deep documentation hierarchy
Split documentation per version
Notify people about edits or new documentation
Make comments more useful

Documentation section

18 of 45

[Survey / Analytics data]
Story map
Wireframe
Usability testing
Modify wireframes, visual design
Usability testing
Build

Our process

19 of 45

Documentation page

Documentation guide

Documentation page

20 of 45

21 of 45

22 of 45

23 of 45

24 of 45

25 of 45

Inside of the guide is the documentation itself, here is a mockup of a documentation page.

We removed a lot of clutter overall. And a lot of information that was not helpful to users, or information we could present in a different way.

You can see breadcrumbs very prominent on top. In our usability testing we found that they are very important in terms of helping people understand where the page they are looking at is located in the overall IA.

Page title is fairly short in this example. We will actually be introducing some restrictions on the length of the title, because some of them are just way too long.

Last updated date is pretty prominent too. In our survey last updated date was by far the most important bit of metadata people use to evaluate if the page is relevant and up-to-date.

On the right you can see bit green Edit button. We got rid of a whole bunch of tabs, they are hidden behind that drop down. The main thing we want people to do on this page is edit it, and so that is the most prominent CTA.

On the right you can see menu of the guide this page is in.

Hierarchy is flat. As in, there is only one menu level within a guide, all pages are on the same level. If you need to have a level below, you need to create a new guide.

Hierarchy will be created by guides inside of guides. The idea is you will only do it if there is separate enough topic to have a whole guide about it.

Things in the middle are call outs to highlight important information.

Copyright statement is at the bottom.

26 of 45

27 of 45

28 of 45

29 of 45

30 of 45

31 of 45

Following and email notifications for individual pages and guides
WYSIWYG editor and syntax highlighting for code
Related content
'Official' guides for projects
Displaying guides on maintainer's user profiles

Additionally..

32 of 45

Some of the things are already done

33 of 45

Some of the things are already done

34 of 45

Recruit maintainers for part of documentation
Create initial structure of guides and sub-guides
Audit and migration
Win!

Migration

35 of 45

Drupal 8 User Guide

36 of 45

37 of 45

Drupal 8 User Guide

Curated Drupal documentation
Replace key portions of the Drupal.org community documentation with curated documentation
Create version dependent documentation

38 of 45

Drupal 8 User Guide

https://drupal.org/project/user_guide
Written in AsciiDoc
Version control with Git
Reviews, and updates in the issue queue

39 of 45

40 of 45

Drupal 8 User Guide - Current Status

Initial draft of all 99 identified topics is complete! Woohoo!
Copy editing for adherence to guidelines in-progress
Copy editing for consistent voice is next up

You can help with this at the sprint on Friday!

41 of 45

Questions we need to solve together

Content audit of existing book pages and migration
Recruiting maintainers for sections
Encouraging higher quality documentation
User guide:....

42 of 45

One last thing...

43 of 45

Sign up to be documentation maintainer

44 of 45

So How Was It? - Tell Us What You Think

Evaluate this session:

bit.ly/docs-session

Thanks!

45 of 45

Join us for Sprints

First-Time Sprinter Workshop - 9am-12pm in Room 271-273

Mentored Core Sprint - 9am-6pm in Room 275-277

General Sprints - 9am-6pm in Room 278-282

Friday, May 13 at the Convention Center