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

    View full-size slide

  2. If you are:
    @DjevaLoperka

    View full-size slide

  3. If you are:
    @DjevaLoperka
    ● trying to be an open source contributor

    View full-size slide

  4. If you are:
    @DjevaLoperka
    ● trying to be an open source contributor
    ● trying to be an open source user

    View full-size slide

  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

    View full-size slide

  6. Is it really needed?
    @DjevaLoperka
    really

    View full-size slide

  7. Misconceptions:
    @DjevaLoperka

    View full-size slide

  8. Misconceptions:
    @DjevaLoperka
    ● “Code should be self-documented.”

    View full-size slide

  9. Misconceptions:
    @DjevaLoperka
    ● “Code should be self-documented.”
    ● “It’s obvious how to use our software. Users will know.”

    View full-size slide

  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.”

    View full-size slide

  11. @DjevaLoperka

    View full-size slide

  12. @DjevaLoperka

    View full-size slide

  13. @DjevaLoperka

    View full-size slide

  14. @DjevaLoperka

    View full-size slide

  15. @DjevaLoperka

    View full-size slide

  16. WordPress Docs
    @DjevaLoperka
    Making

    View full-size slide

  17. Pros Cons
    @DjevaLoperka

    View full-size slide

  18. Pros Cons
    @DjevaLoperka
    ● Everyone can edit

    View full-size slide

  19. Pros Cons
    @DjevaLoperka
    ● Everyone can edit
    ● One account needed

    View full-size slide

  20. Pros Cons
    @DjevaLoperka
    ● Everyone can edit
    ● One account needed
    ● Version control

    View full-size slide

  21. Pros Cons
    @DjevaLoperka
    ● Everyone can edit
    ● One account needed
    ● Version control
    ● Everyone can edit

    View full-size slide

  22. Pros Cons
    @DjevaLoperka
    ● Everyone can edit
    ● One account needed
    ● Version control
    ● Everyone can edit
    ● Everyone can edit

    View full-size slide

  23. Pros Cons
    @DjevaLoperka
    ● Everyone can edit
    ● One account needed
    ● Version control
    ● Everyone can edit
    ● Everyone can edit
    ● Everyone can edit

    View full-size slide

  24. Codex New docs
    @DjevaLoperka

    View full-size slide

  25. Codex New docs
    ● Wiki ● WordPress
    @DjevaLoperka

    View full-size slide

  26. Codex New docs
    ● Wiki
    ● One account
    ● WordPress
    ● At least two accounts
    @DjevaLoperka

    View full-size slide

  27. Codex New docs
    ● Wiki
    ● One account
    ● Everyone can create docs
    ● WordPress
    ● At least two accounts
    ● Few can create docs
    @DjevaLoperka

    View full-size slide

  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

    View full-size slide

  29. The issue of
    @DjevaLoperka
    reporting issues

    View full-size slide

  30. End user docs:
    @DjevaLoperka

    View full-size slide

  31. End user docs:
    @DjevaLoperka
    ● Project code name “HelpHub”

    View full-size slide

  32. End user docs:
    @DjevaLoperka
    ● Project code name “HelpHub”
    ● wordpress.org/support

    View full-size slide

  33. End user docs:
    @DjevaLoperka
    ● Project code name “HelpHub”
    ● wordpress.org/support
    ● Two parts:

    View full-size slide

  34. End user docs:
    @DjevaLoperka
    ● Project code name “HelpHub”
    ● wordpress.org/support
    ● Two parts:
    ○ General

    View full-size slide

  35. End user docs:
    @DjevaLoperka
    ● Project code name “HelpHub”
    ● wordpress.org/support
    ● Two parts:
    ○ General
    ○ Block editor

    View full-size slide

  36. End user docs:
    @DjevaLoperka
    ● Project code name “HelpHub”
    ● wordpress.org/support
    ● Two parts:
    ○ General
    ○ Block editor

    View full-size slide

  37. End user docs:
    @DjevaLoperka
    ● Project code name “HelpHub”
    ● wordpress.org/support
    ● Two parts:
    ○ General
    ○ Block editor

    View full-size slide

  38. Developer docs:
    @DjevaLoperka

    View full-size slide

  39. Developer docs:
    @DjevaLoperka
    ● Project code name “DevHub”

    View full-size slide

  40. Developer docs:
    @DjevaLoperka
    ● Project code name “DevHub”
    ● developer.wordpress.org

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  46. Contributor docs:
    @DjevaLoperka

    View full-size slide

  47. Contributor docs:
    @DjevaLoperka
    ● Team’s blog and handbook

    View full-size slide

  48. Contributor docs:
    @DjevaLoperka
    ● Team’s blog and handbook
    ● make.wordpress.org

    View full-size slide

  49. Contributor docs:
    @DjevaLoperka
    ● Team’s blog and handbook
    ● make.wordpress.org
    ● Contribution processes

    View full-size slide

  50. @DjevaLoperka

    View full-size slide

  51. @DjevaLoperka

    View full-size slide

  52. The perfect tool:
    @DjevaLoperka

    View full-size slide

  53. The perfect tool:
    @DjevaLoperka
    ● Reporting issues on the spot

    View full-size slide

  54. The perfect tool:
    @DjevaLoperka
    ● Reporting issues on the spot
    ● Not creating additional work for active contributors

    View full-size slide

  55. The perfect tool:
    @DjevaLoperka
    ● Reporting issues on the spot
    ● Not creating additional work for active contributors
    ● Automate everything

    View full-size slide

  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 󰜅

    View full-size slide

  57. The transition tool:
    @DjevaLoperka

    View full-size slide

  58. The transition tool:
    @DjevaLoperka
    ● A central place for reporting all issues

    View full-size slide

  59. The transition tool:
    @DjevaLoperka
    ● A central place for reporting all issues - possibility for extending

    View full-size slide

  60. The transition tool:
    @DjevaLoperka
    ● A central place for reporting all issues - possibility for extending
    ● A central place for working on any issue

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  63. What about
    @DjevaLoperka
    Gutenberg

    View full-size slide

  64. Gutenberg:
    @DjevaLoperka

    View full-size slide

  65. Gutenberg:
    @DjevaLoperka
    ● PHP + React.js

    View full-size slide

  66. Gutenberg:
    @DjevaLoperka
    ● PHP + React.js
    ● Change will always be rejected by some

    View full-size slide

  67. Gutenberg:
    @DjevaLoperka
    ● PHP + React.js
    ● Change will always be rejected by some
    ● Documentation debt

    View full-size slide

  68. The best documentation
    is written by those who are
    using it.
    @DjevaLoperka

    View full-size slide

  69. Long story short..
    @DjevaLoperka

    View full-size slide

  70. Moving forward:
    @DjevaLoperka

    View full-size slide

  71. Moving forward:
    @DjevaLoperka
    ● Google Season of Docs 2020

    View full-size slide

  72. Moving forward:
    @DjevaLoperka
    ● Google Season of Docs 2020
    ● WordPress releases

    View full-size slide

  73. Moving forward:
    @DjevaLoperka
    ● Google Season of Docs 2020
    ● WordPress releases
    ● Collaborating with other teams

    View full-size slide

  74. Moving forward:
    @DjevaLoperka
    ● Google Season of Docs 2020
    ● WordPress releases
    ● Collaborating with other teams
    ● Paired programming / documenting

    View full-size slide

  75. @DjevaLoperka

    View full-size slide

  76. @DjevaLoperka

    View full-size slide

  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/

    View full-size slide

  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]

    View full-size slide

  79. Milana Cap
    Thank you
    Twitter:
    GitHub:
    WordPress:
    WordPress Slack:
    Email:
    @DjevaLoperka
    @zzap
    @milana_cap
    @zzap
    [email protected]

    View full-size slide