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

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

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

Pedro Nauck

June 16, 2018
Tweet

More Decks by Pedro Nauck

Other Decks in Technology

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