공식 문서를 모은 사이트를 개발했습니다

시작하며

최근 개발을 시작하기 전에 공식 문서를 먼저 읽는 경우가 많아졌습니다. 그래서 제가 사용하기 위해서 공식 문서를 모은 사이트를 만들었습니다. 이 글에서는 사이트의 개발에 대해 소개하겠습니다.

공식 문서가 중요한 이유

최근 제가 이 문서를 모은 사이트를 만드는 것이 무의미하다고 말하는 사람들이 있었습니다. 몇몇 사람들은 모든 것을 생성형 AI에 맡기면 된다고 합니다. 하지만 저는 공식 문서가 중요하다고 생각합니다. 그 이유를 아래에 설명하겠습니다.

1. 생성형 AI의 보급으로 공식 문서의 중요성이 더 커졌습니다

최근 개발을 할 때는 직접 코딩하는 것보다 생성형 AI(ChatGPT, Claude 등)를 사용해 개발하는 것이 일반적입니다. 그래서 직접 코드를 작성하는 것보다 AI에 어떤 지시를 내릴지가 중요합니다. 라이브러리를 어떻게 사용할지 구체적으로 지시를 내리려면 단순한 코딩 능력 이상의 지식이 필요합니다. 또한 아직 생성형 AI는 완벽하지 않습니다.

예를 들어, 반년 전에 제가 Next.js로 블로그를 구축할 때, 저는 'Page Router'가 아닌 'App Router'를 사용해 개발을 진행했습니다. 하지만 ChatGPT가 알려준 코드는 대부분 'Page Router'를 사용한 것이었습니다. 현재는 'App Router'가 학습 데이터에 포함되어 있어 이런 문제는 해결되었지만, 이런 문제(할루시네이션)가 발생하는 경우가 많습니다. 만약 제가 이 두 'Router'에 대한 이해가 부족했다면, ChatGPT에 잘못된 정보를 배워 개발을 하지 못했을 수도 있습니다.

2. 결국 문제가 발생했을 때는 공식 문서를 보는 경우가 많습니다

개발을 하다 보면 어쩔 수 없이 문제가 발생합니다. 그때 최종적으로 도달하는 곳은 두 가지입니다. 하나는 공식 문서를 보는 것입니다. 다른 하나는 Stack Overflow 같은 커뮤니티입니다. 공식 문서를 볼 수 있다면 문제를 쉽게 해결할 수 있는 경우가 많습니다.

예를 들어, 최근 저는 제 블로그를 리팩토링했습니다. 이 과정에서 next-mdx-remote를 도입했습니다. ChatGPT에 이것을 사용하라고 시켰지만 오류가 발생했습니다. 저는 Next.js의 page.tsx 안에서 Markdown을 처리하도록 코드를 작성했습니다. 따라서 Markdown을 처리하기 위해서는 RSC(React Server Component)를 사용해야 했습니다. 공식 Github Repository의 README.md를 보면 next-mdx-remote/rsc를 이용하면 쉽게 처리할 수 있다고 설명이 있습니다.

import { MDXRemote } from "next-mdx-remote/rsc";
 
// app/page.js
export default function Home() {
  return (
    <MDXRemote
      source={`# Hello World
 
      This is from Server Components!
      `}
    />
  );
}

하지만 ChatGPT나 Claude에 물어봐도 next-mdx-remote/rsc를 사용하는 코드는 알려주지 않았습니다. 아마도 최신 정보가 학습 데이터에 포함되지 않았던 것 같습니다. 저는 위의 코드를 응용해서 서버 사이드에서 Markdown을 사용할 수 있도록 이렇게 코드를 작성했습니다.

// MDX 컴파일 시 코드 하이라이팅 추가
const { content, frontmatter } = await compileMDX<{
  title: string;
  date: string;
  image: string;
}>({
  source: fileContent,
  options: {
    parseFrontmatter: true,
    mdxOptions: {
      remarkPlugins: [remarkGfm], // GitHub Flavored Markdown 사용
      rehypePlugins: [
        [
          rehypePrettyCode,
          {
            theme: "github-light", // 원하는 테마 설정
          },
        ],
      ],
    },
  },
});
 
return (
  <div className="flex items-center justify-center min-h-screen">
    <div className="markdown-body w-full md:w-3/5">
      <div className="my-56"></div>
      {content}
      <div className="my-56"></div>
    </div>
  </div>
);

이렇게 공식 문서를 보면 의외로 쉽게 해결할 수 있는 경우가 많습니다.

3. 라이브러리나 프레임워크 공식 문서에는 설계 사상이 담겨 있습니다

라이브러리나 프레임워크의 공식 문서에는 그 라이브러리나 프레임워크의 설계 사상이 담겨 있습니다. 예를 들어, "왜 React를 사용하나요? 다른 라이브러리보다 뭐가 좋나요?"라는 질문에 대해 바로 답변이 나오지 않는다면 React에 대한 이해가 부족하다고 할 수 있습니다. 예를 들어 공식 문서에는 컴포넌트의 순수성이 중요한 이유를 이렇게 적고 있습니다.

멱등성(idempotent)을 가질 것 - 같은 입력으로 실행할 때마다 항상 같은 결과를 얻을 것. 컴포넌트의 입력은 props와 state, 그리고 context입니다. 훅의 입력은 그 인수입니다. 렌더링 시 부작용이 없을 것 - 부작용(side effect)을 동반하는 코드는 렌더링과는 별도로 실행해야 합니다. 예를 들어 사용자가 UI를 조작하고 그로 인해 UI가 업데이트되는 경우는 이벤트 핸들러로, 또는 렌더링 직후에 동작시키는 경우는 이펙트로 실행합니다. 로컬 값 이외의 것을 변경하지 않을 것: 컴포넌트와 훅은 렌더링 중에 로컬에서 생성된 것이 아닌 값을 절대 변경해서는 안 됩니다.

이렇게 공식 문서에도 적혀 있음에도 불구하고 현장에서의 코드를 보면 이 설계 사상에 반하는 경우가 많습니다. 컴포넌트 관리가 전혀 되지 않은 React 코드를 본 적이 수없이 많습니다. 공식 문서를 읽음으로써 이러한 설계 사상을 이해하고 문제를 피할 수 있습니다.

번역 진행 방향

개인적인 프로젝트에는 대부분 JavaScript와 관련 기술만 사용하고 있어서 이것들부터 번역하고 싶습니다. 하지만 현재 제 회사에서 사용하고 있는 기술은 Spring Framework, Thymeleaf, PostgreSQL, Docker, Kafka, Kubernetes 등이라 이것들의 번역이 먼저 진행될 예정입니다. 그리고 JavaScript와 관련된 문서를 번역할 예정입니다.

마치며

아직 대부분의 공식 문서 번역은 되어있지 않지만, 점점 번역해 나갈 예정입니다. 언젠가 누군가에게 이 사이트가 도움이 될 거라고 믿고 있습니다.

0
Creative Commons