How Vuepress helped my documentation
Just a couple of hours and the site is up
As one teacher told me once, “Software lives and dies by its documentation”. True to be told, event the most intuitive software needs some kind of manual, and when creating packages for Packagist and NPM you also expects, at least, some lines of instructions.
Larawiz is not the exception. The package is basically a free database scaffolder with braindead syntax, meaning, you can easily get the grasp of it without reading any documentation and know what you’re gonna get in your Laravel project:
models:
User:
name: string
email: string
password: string
posts: hasMany Post:
title: string
body: text
user: belongsTo
The problem it’s when you need to do something that you don’t have a hint about how to do. For example, use UUID as primary key, or use a Pivot model. That’s when you need to read the documentation, and that’s when the end user becomes fond of your software or uninstalls it to look for something less complex.
From Gitbooks…
Gitbooks became my first choice for the documentation: very intuitive, mostly graphical, supports a sort of “autosaved drafts” and multiple drafts, everything without a line of code or push/pull or knowing what git is. It integrated like a breeze to the fresh repository to hold everything.
The great feature of Gitbooks is not what is is, but how it uses your browser to help you write like your best days in Microsoft Word. You have many tools at your disposal, without having to code anything, so you feel pretty much at home.
The first problem is that for some people felt the site was not very agile. While it’s pretty, free accounts have some limitations, and having the documentation under my username it’s not very good:
https://johndoecussings.gitbook.com/docsApart from that, there is little control on the theme itself apart from the free one, which is good enough for anybody looking for something simpler but not for me.
Then I stumbled upon Vuepress, the same site engine used by the folks on Vue for their documentation. And now the documentation runs on that.
…to Vuepress
So, how was the change? Well, Vuepress offers flexibility and some features that are not available in Gitbooks, at least not a first glance, like line code highlight. While there are features that the vanilla Vuepress theme doesn’t offer, there is a comprehensive list of plugins that makes it more complete.
Of course the changes were not without some issues, but nevertheless, it took less than an hour with some search-and-replace REGEX and changing the directories.
What took most time was the latter, changing the directories. Vuepress likes single-level sections, so trying to bury a section inside another is not very good.
Talking about the navigation, you go full manual on that. Vuepress tries to push you to have one big single page with multiple title anchors so all these can be shown in the sidebar, so if you are not using that style of arrangement, you will need to make a sidebar manually since Vuepress can’t guess the order of the files and sections you want to show.
If that’s not your taste, mainly because you have multiple sections without a single flow to connect them, you are bound to create your own sidebar. Again, Vuepress is not that difficult and the sidebar was created in a breeze, but for people who don’t know what is JSON or YAML, it may be a great problem.
One good feature that offers Vuepress out of the box is the “splash” home page. It was created in less than minute.
The only problem that Vuepress may pose over many people is that is not a graphical tool, but a very verbose one. People without coding knowledge or that cannot feel at easy puking code instead of a WYSIWYG editor, won’t be using Vuepress at all. The engine doesn’t offer a graphical interface nor tools to push a documentation over the internet — in the case of Larawiz, it was uploaded to Github Pages — so you’re bound to what you have, being that your favorite IDE or Notepad++.
I can see the appeal of Gitbooks for non-tech-savvy people that need to document something but stay more in the graphical side of things, and are willing to pay for more features instead of paying with time and dedication to use Vuepress at all, which includes having the documentation actually available in the Internerks. It’s just that, the last time I try to communicate with the folks at Gitbooks over a bug, I received nothing more than silence.
Vuepress needs some configuration first, specially on the sidebar, while Gitbooks won’t bat an eye and guess most of the things to make your documentation feature complete. If you don’t want to push some strings in a YAML file (as I decided instead of going with plain JSON) and edit vanilla Markdown files without a GUI, then Vuepress may be not for you, but again, who are those people who create documentation and are not familiarized with git, Markdown and Javascript?
So, it’s Vuepress any good?
Going back to the documentation of Larawiz, yes, it’s good. Having flexibility on the theme makes it already better than Gitbooks, but I will miss the clearer GUI that offered to make text blocks like headers, hints, and some advanced syntax, at the grasp of a click. I literally miss pressing CTRL + / to open a menu with the different blocks of text I could add, which makes me focus on what to write, rather on verbosing my way up into the documentation.
Fortunately, Larawiz doesn’t uses advanced things, and if it needs something out of Vuepress, you can use a third party plugin or make it yourself.
I probably won’t look back unless something better than Vuepress comes out. Hopefully, the next thing Vuepress team pushes out, is a GUI and automatic publishing to sites like Github pages, Gitlab pages, who knows. This means, less time configuring and downloading plugins, and more time actually using Vuepress to what was meant to fix.
About the documentation, you can give it a go and try Larawiz by yourself.
