DEV Community

Cover image for Issue or Documentation?
Sibelius Seraphini for Woovi

Posted on

Issue or Documentation?

issue-or-doc

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

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

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

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

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

Top comments (2)

Collapse
 
vinibgoulart profile image
Vinicius Blazius Goulart

Awesome!

Collapse
 
tgmarinhodev profile image
Thiago Marinho

interesting