VuePress: Documentation Made Easy

Slide 1

VUEPRESS DOCUMENTATION MADE EASY Ben Hong @bencodezen

Slide 2

Slide 3

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

Slide 4

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

Slide 5

LET’S TAKE A STROLL DOWN MEMORY LANE

Slide 6

Slide 7

Slide 8

Slide 9

INHALE… EXHALE…

Slide 10

Slide 11

“Wisdom of the Ancient” by xkcd

Slide 12

SO WHAT IS THE PROBLEM?

Slide 13

Slide 14

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.”

Slide 15

Calvin and Hobbes for January 22, 1986

Slide 16

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

Slide 17

Slide 18

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

Slide 19

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

Slide 20

Slide 21

BUT WAIT… WE’RE DEVELOPERS

Slide 22

WE GOT THIS! FO SHO

Slide 23

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

Slide 24

Slide 25

Slide 26

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

Slide 27

So tell me more about this VuePress thing…

Slide 28

Slide 29

Slide 30

VUEPRESS

Slide 31

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

Slide 32

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

Slide 33

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

Slide 34

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

Slide 35

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

Slide 36

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

Slide 37

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

Slide 38

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

Slide 39

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

Slide 40

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

Slide 41

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

Slide 42

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

Slide 43

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

Slide 44

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

Slide 45

THE VUE PART OF VUEPRESS VUE MAGIC: INTERPOLATION

Slide 46

THE VUE PART OF VUEPRESS VUE MAGIC: DIRECTIVES

Slide 47

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

Slide 48

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

Slide 49

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

Slide 50

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