A presentation at Connect.Tech 2018 in in Atlanta, GA, USA by Ben Hong
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
For those who have been lucky enough to work with Vue.js documentation, you know that it’s one of the best out there in the ecosystem. And true to the ethos of the Vue.js ecosystem, Evan You has just come out with another tool that makes documentation a piece of cake. In this talk, we’ll be going over what VuePress is along with why you should have it in your arsenal of tools!
The following resources were mentioned during the presentation or are useful additional information.
The official VuePress docs that will be very handy as you learn how to configure your VuePress site!
A tutorial that can help you get up and running pretty quickly. Some of the information in the advanced sections are a little out of date, but that can be easily reconciled by the official docs.
And in case you're wondering, yes I plan to write my own for everyone. More on that soon!
for free. You
can too.