Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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.

WordPress Greek Community

April 09, 2022
Tweet

More Decks by WordPress Greek Community

Other Decks in Technology

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 [email protected]
  79. Milana Cap Thank you Twitter: GitHub: WordPress: WordPress Slack: Email:

    @DjevaLoperka @zzap @milana_cap @zzap [email protected]