Documentation is Getting an Overhaul

Having high-quality documentation available for Drupal.org is key to gaining wider adoption, growing the community, and the overall success of the Drupal project.

In this presentation we've shared the status and future plans for various documentation related initiatives ran by community volunteers and the Drupal Association staff.

Presented at DrupalCon New Orleans 2016 with @eojthebrave.

Transcript

1. Documentation Is Getting an Overhaul eojthebrave & tvn
2. 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
3. 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.
4. 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.
5. State of Documentation ✤ Drupal 8 documentation continues to improve ✤ Lots of blog posts, videos, and non-drupal.org content
6. 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
7. What is happening with our tools? ✤ API documentation (api.drupal.org) ✤ Community documentation on Drupal.org ✤ Drupal 8 User Guide
8. api.drupal.org
9. Thank yous ✤ Jennifer Hodgdon ✤ Neil Drumm
10. Recent Changes ✤ New curated landing page ✤ Syntax highlighting ✤ Works with minor version releases ✤ Updates to work better with Drupal 8 ✤ Responsive design ✤ Solr indexing
11. Community documentation on Drupal.org
12. Thank yous Contributions in the last year ✤ 791 people with 2 or more edits ✤ They made 7701 edits
14. More info: DrupalCon Barcelona presentation, Issue queue Part of the overall content restructure effort
16. ✤ 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
17. ✤ [Survey / Analytics data] ✤ Story map ✤ Wireframe ✤ Usability testing ✤ Modify wireframes, visual design ✤ Usability testing ✤ Build Our process
18. Documentation page Documentation page Documentation guide Documentation page
30. ✤ 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..
31. Some of the things are already done
32. Some of the things are already done
33. 1. Recruit maintainers for part of documentation 2. Create initial structure of guides and sub-guides 3. Audit and migration 4. Win! Migration
34. Drupal 8 User Guide
36. Drupal 8 User Guide ✤ Curated Drupal documentation ✤ Replace key portions of the Drupal. org community documentation with curated documentation ✤ Create version dependent documentation
37. 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. 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!
40. Questions we need to solve together ✤ Content audit of existing book pages and migration ✤ Recruiting maintainers for sections ✤ Encouraging higher quality documentation ✤ User guide:....
41. One last thing...
42. Sign up to be documentation maintainer
43. So How Was It? - Tell Us What You Think Evaluate this session: bit.ly/docs-session Thanks!
44. 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