Issue or Documentation?

#automation #documentation #writing

At Woovi we don't like to spend time discussion non-important things.
One common question was if a developer should write in an issue or add a new documentation item in our internal documentation.
We made a script to make it easy to convert from a GitHub issue to a markdown format of our documentation, so we don't need to discuss about this anymore.

Transforming an issue in a markdown

yarn es ./scripts/issue.ts <https://github.com/<owner>/<repo>/issues/43155>

yarn es is an alias to node -r esbuild-register, it run node using esbuild to support TypeScript and modern JavaScript.

The first thing we need to do is to read the command line arguments to extract the issue path

const [, , ...unsanitizedArgs] = process.argv;

const [url] = unsanitizedArgs;

Then we need to parse url to extract issue number

const getIssueNumber = (url: string) => {
const tokens = url.split("/");

if (tokens.length !== 7) {
  return null;
}

const [issueNumber] = tokens[6].split("#");

return issueNumber;
};

Then we need to get the issue content from GitHub API

const octokit = new Octokit({
  auth: config.GITHUB_TOKEN,
});

const issue = await octokit.rest.issues.get({
  owner,
  repo,
  issue_number: issueNumber,
});

After this, you just need to create the markdown with the correct format and save it to a file

const id = slug(issue.data.title);
const title = issue.data.title;
const body = issue.data.body.split("\r\n").join("\n");

const md = `---
id: ${id}
title: "${title}"
tags: 
- dev-docs
---

${body}
`;

const mdFile = path.join(cwd, 'md', `${id}.md`);

await writeFile(mdFile, md);

After this, the developer just needs to copy the file to the docusaurus internal documentation.

To summarize

At Woovi we try to avoid wasting time bikeshedding, discussing non-important issues. We prefer to focus our time in hard issues that will move the needle to make us move forward.
This article is one example of how automation can remove some procrastination or bikeshedding.

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 Damian Zaleski on Unsplash