DEV Community

Cover image for Issue or Documentation?
Sibelius Seraphini for Woovi

Posted on

8

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

Image of Timescale

🚀 pgai Vectorizer: SQLAlchemy and LiteLLM Make Vector Search Simple

We built pgai Vectorizer to simplify embedding management for AI applications—without needing a separate database or complex infrastructure. Since launch, developers have created over 3,000 vectorizers on Timescale Cloud, with many more self-hosted.

Read full post →

Top comments (2)

Collapse
 
vinibgoulart profile image
Vinicius Blazius Goulart •

Awesome!

Collapse
 
tgmarinhodev profile image
Thiago Marinho •

interesting

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more