Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Painless Open Source Documentation with Docusaurus

501 views

Published on

Presented at All Things Open 2018
Presented by Yangshun Tay with Facebook
10/23/18 - 2:00 PM - Case Study/Demo Track

Published in: Technology
  • Be the first to comment

Painless Open Source Documentation with Docusaurus

  1. 1. Painless Open Source Documentation with Docusaurus Yangshun Tay | Front End Engineer
  2. 2. Docusaurus Yangshun Tay, Front End Engineer Getting to Know You • How many of you are project maintainers? • How many of you have a website for your project? • How many of you built your own website? • How many of you built your own website but thought it was very time consuming?
  3. 3. Wait! You are going to talk about documentation?!?
  4. 4. Docusaurus Yangshun Tay, Front End Engineer What?! Documentation?!
  5. 5. Interstitial (Standard)
  6. 6. Docusaurus Yangshun Tay, Front End Engineer Documentation Helps Success? • 17 of the top 20 (85%) most followed GitHub projects have a website • 3 more are documentation repos via README.md • The 17th project (create-react-app) just created a website
  7. 7. Docusaurus Yangshun Tay, Front End Engineer create-react-app (~58,000 stars)
  8. 8. Docusaurus Yangshun Tay, Front End Engineer Documentation helps provide a better user experience for your project
  9. 9. Docusaurus Yangshun Tay, Front End Engineer Documentation Helps Success? • Isn't creating a website time consuming? • Isn't writing documentation hard? • Isn't it hard to add useful features? Slash says "No!"
  10. 10. Docusaurus
  11. 11. Docusaurus Yangshun Tay, Front End Engineer
  12. 12. Docusaurus Yangshun Tay, Front End Engineer Save time and focus on your project's documentation. Simply write docs and blog posts with Markdown and Docusaurus will generate a set of static html files ready to be served.
  13. 13. Docusaurus Yangshun Tay, Front End Engineer Make it easy for your community to find what they need in your documentation. We proudly support Algolia documentation search.
  14. 14. Docusaurus Yangshun Tay, Front End Engineer Localization comes pre-configured. Use Crowdin to translate your docs into over 70 languages.
  15. 15. Docusaurus Yangshun Tay, Front End Engineer Change the look and feel of your project pages by using React. Docusaurus can be extended while reusing the same header and footer.
  16. 16. Docusaurus Yangshun Tay, Front End Engineer Support users on all versions of your project. Document versioning helps you keep documentation in sync with project releases.
  17. 17. Docusaurus Yangshun Tay, Front End Engineer Docusaurus by the Numbers • Started on Jun 2017 • Launched on Dec 14 2017 • 1000+ projects using • 9249 stars
  18. 18. Demo
  19. 19. Docusaurus Yangshun Tay, Front End Engineer https://docusaurus.io/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus
  20. 20. Large Community
  21. 21. Docusaurus Yangshun Tay, Front End Engineer https://docusaurus.io/users
  22. 22. Docusaurus Yangshun Tay, Front End Engineer React Native (~70,000 stars)
  23. 23. Docusaurus Yangshun Tay, Front End Engineer Babel (~30,000 stars)
  24. 24. Docusaurus Yangshun Tay, Front End Engineer Prettier (~28,000 stars)
  25. 25. Docusaurus Yangshun Tay, Front End Engineer Jest (~21,000 stars)
  26. 26. Docusaurus Yangshun Tay, Front End Engineer Reason (~6,500 stars)
  27. 27. Critical Feedback
  28. 28. Docusaurus Yangshun Tay, Front End Engineer Docusaurus is not perfect
  29. 29. Docusaurus Yangshun Tay, Front End Engineer
  30. 30. We are listening!
  31. 31. Docusaurus 2
  32. 32. Docusaurus Yangshun Tay, Front End Engineer https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2
  33. 33. Demo Again!
  34. 34. v1 vs v2
  35. 35. Docusaurus Yangshun Tay, Front End Engineer V1 (Website) V2 (Single Page App) Rendering Purely server side Server side (initial load) Client side (subsequent page transitions) Versioning Diff-based approach Snapshot-based approach Styles Traditional CSS Lives in vendor land CSS Modules / Sass Lives in user land Layout Fixed Customizable Themes No Yes! Via CSS variables (?) Routing Express React Router + SSR Bundling Custom scripts Webpack
  36. 36. Alternatives
  37. 37. Docusaurus Yangshun Tay, Front End Engineer
  38. 38. Docusaurus Yangshun Tay, Front End Engineer We just want open source project owners to consider documentation as first-class component to their project
  39. 39. Takeaways
  40. 40. Docusaurus Yangshun Tay, Front End Engineer What did we learn? • Docusaurus makes it really simple to create a website • v1 provides common features out of the box • v2 will have the best qualities of v1 but even more extensible • Docusaurus is building a community of small and large sites alike Docs can be fun!
  41. 41. Docusaurus Yangshun Tay, Front End Engineer Docusaurus Maintainers Yangshun Tay Joel Marcey Endilie Yacop Sucipto @JoelMarcey JoelMarcey @endiliey@yangshunz yangshun endiliey
  42. 42. Docusaurus Yangshun Tay, Front End Engineer Project Information Slash @docusaurus facebook/docusaurus #docusaurus-users #docusaurus-dev
  43. 43. Docusaurus Yangshun Tay, Front End Engineer Thank you!
  44. 44. Q & A

×