Docz - It has never been so easy to document your things!

📎 More info: https://github.com/pedronauck/docz

Transcript

1. It has never been so easy to document your things!
   

   View Slide

2. Pedro Nauck
   @pedronauck
   

   View Slide

3. View Slide

4. Inspiration
   

   View Slide

5. View Slide

6. View Slide

7. View Slide

8. View Slide

9. Styleguides
   

   View Slide

10. View Slide

11. View Slide

12. ⚙ Need setup
    ⛏ Hard/impossible to customize
    # Complex codebase
    Heavy and slow
    Pain
    

    View Slide

13. Zero config and easy
    ⚡ Blazing Fast
    Easy to customize
    MDX Based
    Pluggable
    Typescript and Flow Support
    Solution
    

    View Slide

14. Zero-config
    ➡ Run without complex configurations
    ➡ Easy to setup and use
    ➡ No strict architectures
    

    View Slide

15. View Slide

16. View Slide

17. Blazing fast
    ➡ Fast build with webpack 4
    ➡ Automatic code splitting
    ➡ Hot reload that works
    

    View Slide

18. View Slide

19. Easy to customize
    ➡ Create your own style
    ➡ Share and create themes
    

    View Slide

20. View Slide

21. MDX Based
    ➡ Markdown with components
    ➡ Easy to write and understand
    ➡ Built-ins components
    ➡ Remark and Rehype ecosystem
    

    View Slide

22. Is a tree representation of the abstract
    syntactic structure of source code written in a
    programming language
    AST
    

    View Slide

23. View Slide

24. unified is an interface for processing text using syntax trees.
    

    View Slide

25. View Slide

26. View Slide

27. View Slide

28. View Slide

29. View Slide

30. 1. Parse: Text => MDAST
    2. Transpile: MDAST => MDXAST
    3. Transform: MDX/Remark plugins applied to AST
    4. Transpile: MDXAST => MDXHAST
    5. Transform: Hyperscript plugins applied to AST
    6. Transpile: MDXHAST => JSX
    Transpilation Flow
    

    View Slide

31. Pluggable
    ➡ Third party integration
    ➡ Easy to reuse and install
    

    View Slide

32. View Slide

33. Typescript and Flow
    ➡ Zero config typescript and flow support
    

    View Slide

34. Live code
    

    View Slide

35. How it Works
    

    View Slide

36. YOUR DOCS
    THEME
    BUNDLER
    PLUGINS
    ENTRIES PARSE
    PROJECT CONFIGURATION
    

    View Slide

37. Write app files ‣ Write app files using node file system for bundle
    ‣ Render theme, wrappers and router
    Start devserver
    ‣ Start bundler dev server
    ‣ Get configuration from plugins
    ‣ Watch mdx and configuration file using chokidar
    Create data ‣ Server communication with Websockets
    Parse entries ‣ Get meta information using AST parsing
    

    View Slide

38. Roadmap
    

    View Slide

39. ➡ Testing documentation generation
    ➡ Vue, Preact and Inferno integration
    ➡ Static builds based on routes (SSR)
    ➡ Render popups on the fly (action logger)
    ➡ Fetch data (getInitialData)
    ➡ …
    

    View Slide

40. Some Numbers
    

    View Slide

41. View Slide

42. View Slide

43. View Slide

44. View Slide

45. View Slide

46. View Slide

47. View Slide

48. What I’ve Learned
    

    View Slide

49. ✅ Create something that you're really going to use
    ✅ Explore the current pains and work upon them
    ✅ Work hard to build something good
    ✅ Be patient, your project isn’t a startup
    ✅ Try to find the way between an MVP and a perfect project
    ✅ Make a badass announcement and documentation
    

    View Slide

50. View Slide

51. View Slide

52. https://github.com/pedronauck/docz
    Give us some star
    

    View Slide

53. Questions?
    

    View Slide