People will only do what is easy and fast for them. If something is hard and slow, they will avoid as much as possible. To make writing internal/external documentation and articles easy and fast at Woovi, we introduce templates to generate most common types of documentations and articles.
Hygen - Template Generator
hygen.io is the best code/template generator.
It colocates the templates inside the git repository, so each repository has their own templates, and it is very easy to add more templates and edit old ones.
It uses EJS as the Embedded JavaScript templating.
To start using Hygen in your codebase, you run this command
npx hygen init self
This will generate the templates that can generate new templates
+added: _templates/generator/help/index.ejs.t
+added: _templates/generator/with-prompt/hello.ejs.t
+added: _templates/generator/with-prompt/prompt.ejs.t
+added: _templates/generator/new/hello.ejs.t
+added: _templates/init/repo/new-repo.ejs.t
You can create new templates like this:
When your template does not need to ask anything for the user
npx hygen generator new --name 'category'
When your template ask a few questions to generate the template.
npx hygen generator with-prompt --name 'doc'
Creating templates for documentation
We use docusaurus.io for our internal and external documentation.
We need to generate a new documentation. Let's see how we create a template for the new documentation:
npx hygen generator with-prompt --name 'doc'
+added: _templates/doc/with-prompt/hello.ejs.t
+added: _templates/doc/with-prompt/prompt.js
Let's modify the prompt.js to be like this
module.exports = [
{
type: 'input',
name: 'title',
message: 'Title of the doc',
},
{
type: 'input',
name: 'path',
initial: '/',
mesage: 'Path of the doc',
},
];
A new documentation item needs to have a title
and also a path
.
Let's rename hello.ejs.t to doc.ejs.t, and have this content on it:
---
to: docs/<%= (path || '').replace(/^\//, '').replace(/\/$/, '') %>/<%= h.slug(title) %>.md
---
---
id: <%= h.inflection.dasherize(title.toLowerCase()) %>
title: <%= title %>
tags:
- tag
---
## <%= title %>
This will create a new documentation item, in the correct path, with an id, with an title, and with 1 tag.
To generate a new doc you run the following command
npx hygen doc with-prompt
In Summary
At Woovi we are crazy for optimizations.
Every developer is writing at least 1 new documentation item after this automation was set in place.
Using templates also make sure every documentation has the minimal items that are required, like id
, title
and tags
.
Consistency is key to scale, even in documentation.
Woovi
Woovi is a Startup that enables shoppers to pay as they like. To make this possible, Woovi provides instant payment solutions for merchants to accept orders.
If you want to work with us, we are hiring!
Photo by Bernard Hermant on Unsplash
Top comments (2)
Very helpful advice in this particular post! Itβs the little changes that make the largest changes. Thanks for sharing! Dreamexch ipl
Great advice in this post! Itβs often the small adjustments that lead to significant improvements. Thanks for sharing. Dreamexch