My closing talk at the MODX Meetup in Amsterdam, on March 29th, 2019. The goal of this talk was to tell people more about how they can contribute to MODX, showcasing a community initiative to create new MODX documentation. The meetup was live streamed and can be watched here: https://www.youtube.com/watch?v=eUJxqH2AHuM This talk starts at about 7:34:00.

1. Improving the
MODX Documentation
@mark_hamstra
More for MODX

2. Educating users is critical

3. Educating users is also hard

4. docs.modx.com
● Lots of legacy
● No (public) edit history
● Requires manual account creation
● No approvals for editing
● Single language
● Single version

5. How can we,
the community,
make it better?

6. docs.modx.com
● Lots of legacy - collaborative cleanup, throwing away the old
● No (public) edit history - use version control, like Git
● Requires manual account creation - use existing platform, like GitHub
● No approvals for editing - enforce reviews for all contributions
● Single language - add multilanguage support
● Single version - add version branches

7. https://github.com/modxcms/mab-recommendations/pull/19

8. Why Markdown?
● Very common, almost de facto, rich text file format
● _Easy_ to **write**
○ [Links take getting used to](https://google.com/)
● Easy to read, both by humans and computers
● Renders to HTML
● No lock-in to any particular application
● Additional metadata in “front matter”

9. Why git?
● Decentralised storage (keep your own copy/mirror)
● Branches
● Full edit history: named, date, changes

10. Why GitHub?
● Biggest code sharing platform
● Already used for MODX core & documentation issues
● Pull Requests provide a powerful review tool
● Online editing without needing to understand git

11. How do we do this?
1. Get a copy of the current documentation
2. Convert it from HTML to Markdown
3. Commit markdown to a git repository and publish on GitHub
4. Create a new site to serve the documentation
5. Cleanup and improve content
6. Replace docs.modx.com with new documentation

12. github.com/Mark-H/Docs

13. github.com/Mark-H/Docs

14. github.com/Mark-H/Docs

15. github.com/Mark-H/Docs

16. github.com/Mark-H/Docs

17. github.com/Mark-H/Docs

18. github.com/Mark-H/Docs

19. github.com/Mark-H/Docs

20. With source hosted on GitHub...
● Anyone can propose changes
○ Most edits through just the interface
○ For bigger changes, local editing with git is available
● Reviews are transparent, and required reviews can be set per
language/branch
● The full edit history of every file is available

21. Next: create a site to serve
the documentation to users

22. github.com/Mark-H/DocsApp

23. docs.modx.org

24. So far, so good!

25. What still needs to be done:
● Cleaning up the content
○ Some pages should be rewritten
● Design testing, responsiveness
● Language switch
● Implement Search
● Automating deployments

26. You can help!

27. Join #documentation on the
Community Slack (modx.org)

28. Have you used MODX before?
Then you can help improving the content:
● Check issues at Mark-H/Docs:
○ Conversion issues that need to be manually fixed
○ Pages marked as really outdated
● Check issues at modxcms/Docs:
○ 140+ issues with reported problems
○ Find something you know something about

29. Do you speak another language?
Why not create documentation in your language?
● See Mark-H/Docs source:
○ EN is the primary language
○ RU is in progress
○ NL just getting started

30. Are you a designer or front-end dev?
Then you can help with the design for the documentation site:
● The design is still a work in progress
● Browser/responsive testing
● Join the discussion on Slack and GitHub to coordinate efforts

31. Are you a back-end developer?
Then you can help build the documentation site:
● Check the issues at Mark-H/DocsApp
○ Need some utilities and extra features
○ Audit the code
● All improvements welcome

32. Do you run an agency?
Enable and encourage your staff/contractors to help

33. Together we can make it
easier to learn MODX

34. Docs contributors

35. DocsApp contributors

36. Reminder: check your Goodie Bag!
● Free Commerce “Red” theme
● Free license of choice: Redactor, MoreGallery or ContentBlocks
● Merchandise/goodies
(Valid until May 1st)

37. 5x Silver Envelope

38. Links:
https://docs.modx.org
https://github.com/Mark-H/Docs
https://github.com/Mark-H/DocsApp

39. Links:
https://docs.modx.org
https://github.com/Mark-H/Docs
https://github.com/Mark-H/DocsApp
Have a great weekend!

40. Dinner & Drinks at Hannekes Boom
● Dijksgracht 4
● 19:00

41. Walking tour of Amsterdam
● Tomorrow 11:00
● Meet at CS
● Followed by lunch