DEV Community

Cover image for Automating writing using a template generator
Sibelius Seraphini for Woovi

Posted on

Automating writing using a template generator

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode

When your template ask a few questions to generate the template.

npx hygen generator with-prompt --name 'doc'
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode
+added: _templates/doc/with-prompt/hello.ejs.t
+added: _templates/doc/with-prompt/prompt.js
Enter fullscreen mode Exit fullscreen mode

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',
  },
];
Enter fullscreen mode Exit fullscreen mode

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 %>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

doc-gen

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 (1)

Collapse
 
gwendolyn profile image
GwenDolyn

Very helpful advice in this particular post! It’s the little changes that make the largest changes. Thanks for sharing! Dreamexch ipl