Docs or it didn’t happen - Milana Cap [ΕΝ]

Your code can be all rainbows and unicorns, cutting and shining, but if there’s no documentation, does it even exist? Documentation can make or break your open-source project. Don’t believe me? Let me tell you a story or three about writing and managing documentation for the largest open-source CMS community. The WordPress documentation.

Transcript

1. Docs or it didn’t happen Milana Cap @DjevaLoperka
2. If you are: @DjevaLoperka
3. If you are: @DjevaLoperka • trying to be an open source contributor
4. If you are: @DjevaLoperka • trying to be an open source contributor • trying to be an open source user
5. If you are: @DjevaLoperka • trying to be an open source contributor • trying to be an open source user • trying to be an open source maintainer
6. Is it really needed? @DjevaLoperka really
7. Misconceptions: @DjevaLoperka
8. Misconceptions: @DjevaLoperka • “Code should be self-documented.”
9. Misconceptions: @DjevaLoperka • “Code should be self-documented.” • “It’s obvious how to use our software. Users will know.”
10. Misconceptions: @DjevaLoperka • “Code should be self-documented.” • “It’s obvious how to use our software. Users will know.” • “Real developers write code and have no time for docs.”
11. @DjevaLoperka
12. @DjevaLoperka
13. @DjevaLoperka
14. @DjevaLoperka
15. @DjevaLoperka
16. WordPress Docs @DjevaLoperka Making
17. Pros Cons @DjevaLoperka
18. Pros Cons @DjevaLoperka • Everyone can edit
19. Pros Cons @DjevaLoperka • Everyone can edit • One account needed
20. Pros Cons @DjevaLoperka • Everyone can edit • One account needed • Version control
21. Pros Cons @DjevaLoperka • Everyone can edit • One account needed • Version control • Everyone can edit
22. Pros Cons @DjevaLoperka • Everyone can edit • One account needed • Version control • Everyone can edit • Everyone can edit
23. Pros Cons @DjevaLoperka • Everyone can edit • One account needed • Version control • Everyone can edit • Everyone can edit • Everyone can edit
24. Codex New docs @DjevaLoperka
25. Codex New docs • Wiki • WordPress @DjevaLoperka
26. Codex New docs • Wiki • One account • WordPress • At least two accounts @DjevaLoperka
27. Codex New docs • Wiki • One account • Everyone can create docs • WordPress • At least two accounts • Few can create docs @DjevaLoperka
28. Codex New docs • Wiki • One account • Everyone can create docs • Maintenance nightmare • WordPress • At least two accounts • Few can create docs • Maintenance controlled @DjevaLoperka
29. The issue of @DjevaLoperka reporting issues
30. End user docs: @DjevaLoperka
31. End user docs: @DjevaLoperka • Project code name “HelpHub”
32. End user docs: @DjevaLoperka • Project code name “HelpHub” • wordpress.org/support
33. End user docs: @DjevaLoperka • Project code name “HelpHub” • wordpress.org/support • Two parts:
34. End user docs: @DjevaLoperka • Project code name “HelpHub” • wordpress.org/support • Two parts: ◦ General
35. End user docs: @DjevaLoperka • Project code name “HelpHub” • wordpress.org/support • Two parts: ◦ General ◦ Block editor
36. End user docs: @DjevaLoperka • Project code name “HelpHub” • wordpress.org/support • Two parts: ◦ General ◦ Block editor
37. End user docs: @DjevaLoperka • Project code name “HelpHub” • wordpress.org/support • Two parts: ◦ General ◦ Block editor
38. Developer docs: @DjevaLoperka
39. Developer docs: @DjevaLoperka • Project code name “DevHub”
40. Developer docs: @DjevaLoperka • Project code name “DevHub” • developer.wordpress.org
41. Developer docs: @DjevaLoperka • Project code name “DevHub” • developer.wordpress.org • 8 handbooks: Code reference, Coding standards, Block editor, Common APIs, Themes, Plugins, REST API and WP-CLI
42. Developer docs: @DjevaLoperka • Project code name “DevHub” • developer.wordpress.org • 8 handbooks: Code reference, Coding standards, Block editor, Common APIs, Themes, Plugins, REST API and WP-CLI
43. Developer docs: @DjevaLoperka • Project code name “DevHub” • developer.wordpress.org • 8 handbooks: Code reference, Coding standards, Block editor, Common APIs, Themes, Plugins, REST API and WP-CLI
44. Developer docs: @DjevaLoperka • Project code name “DevHub” • developer.wordpress.org • 8 handbooks: Code reference, Coding standards, Block editor, Common APIs, Themes, Plugins, REST API and WP-CLI
45. Developer docs: @DjevaLoperka • Project code name “DevHub” • developer.wordpress.org • 8 handbooks: Code reference, Coding standards, Block editor, Common APIs, Themes, Plugins, REST API and WP-CLI
46. Contributor docs: @DjevaLoperka
47. Contributor docs: @DjevaLoperka • Team’s blog and handbook
48. Contributor docs: @DjevaLoperka • Team’s blog and handbook • make.wordpress.org
49. Contributor docs: @DjevaLoperka • Team’s blog and handbook • make.wordpress.org • Contribution processes
50. @DjevaLoperka
51. @DjevaLoperka
52. The perfect tool: @DjevaLoperka
53. The perfect tool: @DjevaLoperka • Reporting issues on the spot
54. The perfect tool: @DjevaLoperka • Reporting issues on the spot • Not creating additional work for active contributors
55. The perfect tool: @DjevaLoperka • Reporting issues on the spot • Not creating additional work for active contributors • Automate everything
56. The perfect tool: @DjevaLoperka • Reporting issues on the spot • Not creating additional work for active contributors • Automate everything • Doesn’t exist but GitHub will do 󰜅
57. The transition tool: @DjevaLoperka
58. The transition tool: @DjevaLoperka • A central place for reporting all issues
59. The transition tool: @DjevaLoperka • A central place for reporting all issues - possibility for extending
60. The transition tool: @DjevaLoperka • A central place for reporting all issues - possibility for extending • A central place for working on any issue
61. The transition tool: @DjevaLoperka • A central place for reporting all issues - possibility for extending • A central place for working on any issue - removing bottleneck
62. The transition tool: @DjevaLoperka • A central place for reporting all issues - possibility for extending • A central place for working on any issue - removing bottleneck • Contribution recognition
63. What about @DjevaLoperka Gutenberg
64. Gutenberg: @DjevaLoperka
65. Gutenberg: @DjevaLoperka • PHP + React.js
66. Gutenberg: @DjevaLoperka • PHP + React.js • Change will always be rejected by some
67. Gutenberg: @DjevaLoperka • PHP + React.js • Change will always be rejected by some • Documentation debt
68. The best documentation is written by those who are using it. @DjevaLoperka
69. Long story short.. @DjevaLoperka
70. Moving forward: @DjevaLoperka
71. Moving forward: @DjevaLoperka • Google Season of Docs 2020
72. Moving forward: @DjevaLoperka • Google Season of Docs 2020 • WordPress releases
73. Moving forward: @DjevaLoperka • Google Season of Docs 2020 • WordPress releases • Collaborating with other teams
74. Moving forward: @DjevaLoperka • Google Season of Docs 2020 • WordPress releases • Collaborating with other teams • Paired programming / documenting
75. @DjevaLoperka
76. @DjevaLoperka
77. Resources: @DjevaLoperka • https://www.writethedocs.org/guide/ • https://developers.google.com/tech-writing • https://readthedocs.org/ • https://opensource.com/resources/what-open-source • Join WordPress community at https://make.wordpress.org/
78. WordPress engineer at XWP - We’re hiring!! 🤩 WordPress Documentation Team representative Milana Cap Twitter: GitHub: WordPress: WordPress Slack: Email: @DjevaLoperka @zzap @milana_cap @zzap milana.cap@xwp.co
79. Milana Cap Thank you Twitter: GitHub: WordPress: WordPress Slack: Email: @DjevaLoperka @zzap @milana_cap @zzap milana.cap@xwp.co