VUEPRESS DOCUMENTATION MADE EASY Ben Hong @bencodezen

VueDC https://www.vuedc.io BEN HONG Lead UI Developer at POLITICO @bencodezen VueMeetups https://www.vuemeetups.org

BEFORE WE GET STARTED… SLIDES WILL BE AVAILABLE ONLINE https://www.twitter.com/bencodezen FOR THE SOCIAL MEDIA FOLKS @bencodezen - #VuePress #ConnectTech18

LET’S TAKE A STROLL DOWN MEMORY LANE

INHALE… EXHALE…

“Wisdom of the Ancient” by xkcd

SO WHAT IS THE PROBLEM?

SO YOU NEED A REASON TO NOT WRITE ANY DOCUMENTATION… COMMON EXCUSES ▸ “Don’t have time. I have to ship X feature.” ▸ “The docs are so outdated I’d to rewrite the whole thing.” ▸ “We will get to it later.” ▸ “It’s too hard.” ▸ “Don’t like writing.” ▸ “Too lazy.” ▸ “Future devs will figure it out.”

Calvin and Hobbes for January 22, 1986

WHY DOCUMENT THINGS? DOCUMENTATION IS THE KEY TO ANY PROJECT’S LONG TERM SUCCESS. Ben Hong

WHY CONFLUENCE IS A NIGHTMARE FOR DOCUMENTING CODEBASES 1. Little to no design control 2. Completely separate from the codebase Confluence 3. It is a yet another application I need to login to 4. Non-standard markdown syntax 5. Default website theme is not responsive 6. Code blocks are a UX nightmare 7. Forget about custom elements 8. It tries to be the document tool for everyone 9. Difficult to customize as you desire 10.Locked into a specific ecosystem without a good exit strategy

Yeah. I’m gonna need you to document that in Confluence…

BUT WAIT… WE’RE DEVELOPERS

WE GOT THIS! FO SHO

SO YOU TRIED TO BUILD YOUR OWN DOCS SITE… OBJECTIVE: BUILD A DOCS SITE WE WILL LOVE Requirements ▸ Easy to write documentation ▸ Easy to maintain ▸ Version controlled ▸ Site should be responsive ▸ It is easy to customize the design

THE REALITY IS THAT GOOD & LIVING DOCUMENTATION IS HARD AT FIRST. BUT, ALL HOPE IS NOT LOST.

So tell me more about this VuePress thing…

VUEPRESS

“ VuePress is a static site generator with a Vue powered theming system that comes with a default theme optimized for technical documentation.

A LITTLE BIT ABOUT VUEPRESS… WHAT DO YOU NEED TO USE VUEPRESS? ▸ Node.js ▸ VuePress Library

WHAT’S SO GREAT ABOUT VUEPRESS? OPTIMIZED FOR TECHNICAL DOCUMENTATION ▸ Write documentation with tools you already know ▸ Can co-exist in the same repo with minimal config

“ Replace (some) training with doc PRs: when trainees review doc PRs, training is made reusable. - Chris Fritz (@chrisvfritz)

WHAT’S SO GREAT ABOUT VUEPRESS? OPTIMIZED FOR TECHNICAL DOCUMENTATION ▸ Can co-exist in the same repo with minimal config ▸ Write documentation with tools you already know ▸ Hot Module Reloading (HMR) during development ▸ Automatically uses folder structure for routing ▸ Built-in Markdown Extensions

WHAT’S SO GREAT ABOUT VUEPRESS? COOL MARKDOWN EXTENSIONS ▸ Front Matter

WHAT’S SO GREAT ABOUT VUEPRESS? COOL MARKDOWN EXTENSIONS ▸ GitHub-Style Tables

WHAT’S SO GREAT ABOUT VUEPRESS? COOL MARKDOWN EXTENSIONS ▸ Code Syntax Highlighting

WHAT’S SO GREAT ABOUT VUEPRESS? COOL MARKDOWN EXTENSIONS ▸ Line Highlighting in Code Blocks

WHAT’S SO GREAT ABOUT VUEPRESS? COOL MARKDOWN EXTENSIONS ▸ Custom Containers

WHAT’S SO GREAT ABOUT VUEPRESS? COOL MARKDOWN EXTENSIONS ▸ Emojis

“ VuePress is a static site generator with a Vue powered theming system that comes with a default theme optimized for technical documentation.

“ VuePress is a static site generator with a Vue powered theming system that comes with a default theme optimized for technical documentation.

THE VUE PART OF VUEPRESS VUE POWERED? TELL ME MORE… ▸ Vue Magic (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧

THE VUE PART OF VUEPRESS VUE MAGIC: INTERPOLATION

THE VUE PART OF VUEPRESS VUE MAGIC: DIRECTIVES

THE VUE PART OF VUEPRESS VUE MAGIC: SITE & PAGE DATA

THE VUE PART OF VUEPRESS: SITE AND PAGE DATA VUE MAGIC: SITE & PAGE DATA

THE VUE PART OF VUEPRESS VUE POWERED? TELL ME MORE… ▸ Vue Magic (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧ ▸ An incredible default theme ▸ Customizable Home Page ▸ Navbar ▸ Sidebar ▸ Built-in Search

THE VUE PART OF VUEPRESS VUE POWERED? TELL ME MORE… ▸ Vue Magic (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧ ▸ An incredible default theme ▸ Customizable Home Page ▸ Navbar ▸ Sidebar ▸ Built-in Search ▸ You can create our own theme

YOU CAN USE VUE COMPONENTS IN YOUR MARKDOWN

THE VUE PART OF VUEPRESS: COMPONENTS IN MARKDOWN

HOW DO I GET STARTED?

HOW DO I GET STARTED? VuePress Official Docs: https://vuepress.vuejs.org/ Tutorial: VuePress Book https://vuepressbook.com/

DOCUMENT ALL THE THINGS

Q&A

THANKS EVERYONE! @BENCODEZEN