News

문서 작성에 Kotlin DSL의 강력한 기능 활용

이 자료는 원래 개발자의 성공과 비즈니스를 지원하는 API 문서 및 개발자 포털의 역할에 초점을맞춘 암스테르담에서 열린 API The Docs 콘퍼런스에서 처음 발표되었습니다. 테크니컬 라이터 직무에서 기술적 측면을 향상하려는 분들에게 이 콘퍼런스를 적극 권장합니다. 모든 강연은 실용적이고 유익하며 라이브 데모를 포함하고 있습니다.

때로는 몇 줄의 코드가 문서 작업을 완료하는 데 도움이 될 수 있습니다. 그러나 문서는 코드가 아니며 문서를 작성할 때 외부 기능이나 자동화를 추가하기가 어려울 수 있습니다. 마치 코드인 것처럼 문서를 작성하고 특정 작업을 완료한 다음, 코드를 다시 문서로 바꿀 수만 있다면 얼마나 좋을까요!

이 블로그 게시물에서는 Kotlin DSL을 사용하여 바로 그렇게 문서를 작성하는 방법을 알아봅니다.

DSL? 어떤 DSL?

DSL 즉, ‘도메인 특화 언어'(Domain-Specific Language)를 정의해 보겠습니다.

간단히 말해서 특정 문제를 해결하도록 설계된 특수 프로그래밍 언어입니다. 언어의 개념과 규칙은 특정 도메인에 따라 다릅니다.

DSL은 작은 언어 또는 문제 지향 언어라고도 합니다. DSL은 특정 문제를 해결하는 데 특화되었기 때문에 이러한 정의는 그 본질을 더 잘 설명합니다.

DSL에는 두 가지 유형이 있습니다. 외부 DSL은 자체 문법, 렉서 및 파서를 가진 별도의 언어입니다. SQL이 이러한 언어의 예입니다. 반면에 내부 DSL은 범용 언어의 문법과 파서를 재사용하고 해당 언어에서 사용 가능한 확장 옵션을 활용합니다.

문서용 Kotlin DSL은 내부 DSL의 범주에 속합니다.

Kotlin을 사용하면 외부 DSL의 모양과 느낌으로 내부 DSL을 빌드할 수 있습니다. 즉, 저희가 개발한 언어는 문서에 특화된 내부 DSL입니다.

JetBrains MPS 웹사이트에서 외부 DSL과 내부 DSL의 차이점에 대해 자세히 알아보세요.

Kotlin DSL의 본질

문서용 Kotlin DSL은 문서와 정적 웹사이트를 만들기 위해 특별히 설계된 프레임워크입니다.

이 프레임워크는 기본 문서 요소에서 작동하는 타입 안전형 빌더이며 추가 기능은 사용자 코드 또는 외부 종속성으로 연결됩니다. 종속성은 특정 소스 또는 출력 형식부터 자연어 처리 기능에 이르기까지 모든 종류의 기능을 제공할 수 있습니다.

테크니컬 라이터는 Kotlin DSL을 사용하여 챕터, 절차, 테이블, 목록 등과 같은 의미론적 요소를 정의할 수 있습니다. 처음에는 자체 마크업에 초점을 맞추었지만 DSL의 유연성 덕분에 맞춤화된 확장이 가능하여 이론적으로 모든 입력 형식을 모든 출력 형식으로 변환할 수 있습니다.

요소 수준에서 사용자가 사용자 지정 요소에 복잡한 논리를 캡슐화할 수 있으며, 그러면 단락이나 목록처럼 간단하게 사용할 수 있습니다.

Kotlin DSL의 중요한 이점 중 하나는 IntelliJ IDEA와 같은 통합 개발 환경(IDE)이 오류 검사, 코드 완성, 리팩터링 등의 지원을 기본 제공한다는 것입니다. 이는 작성된 내용의 품질을 향상하는 데 시키는 데 크게 도움이 됩니다.

중복 탐지의 작동 방식을 보여주는 예

소스가 일반 Kotlin 코드이므로 모든 코드 정보와 언어 지원 기능을 바로 사용할 수 있습니다. 코드를 탐색해야 하나요? 불필요한 코드와 중복된 코드를 찾고 싶으신가요? 아니면 다른 언어를 문자열 리터럴에 삽입하려고 하나요? 이러한 모든 IDE 기능이 Kotlin DSL에서 작동합니다. 언어 자체의 측면에서, Kotlin은 완전한 정적 타입 지정 및 유용한 도구를 얻을 수 있는 전체 에코시스템 등의 큰 이점을 제공합니다.

이 블로그 게시물은 DSL이 사용자 지정 XML 마크업을 생성하는 방법을 보여주지만 특정 요구 사항에 따라 HTML 또는 .docx와 같은 다양한 출력 형식을 생성할 수 있다는 점을 알고 있어야 합니다.

또한 DSL은 IntelliJ IDEA뿐만 아니라 다른 에디터에서, 심지어 명령줄을 통해서도 사용할 수 있습니다. Kotlin 프로그래밍 언어가 제공하는 무한한 가능성을 활용하면서 여전히 내용을 작성하는 것 같은 경험을 제공합니다.

다음은 마크업이 어떻게 표시되는지 보여주는 몇 가지 예입니다.

첫 번째 예에서는 두 개의 목록 항목이 있는 단락과 목록을 만들고 이러한 요소 내에 일부 내용을 추가합니다.

val content = StardustDslContentProvider {
   p { +"Hello, DSL"}
   list {
       li { +"List item 1" }
       li { +"List item 2" }
   }
   this
}

스크립트를 실행하면 다음과 같은 결과가 나타납니다.

두 번째 예에서는 두 개의 열이 있는 표를 만듭니다.

val content = StardustDslContentProvider {
   table {
       tr {
           td {
               +"Parameter name"
           }
           td {
               +"Parameter type"
           }
       }
       tr {
           td {
               +"Value 1"
           }
           td {
               +"Value 2"
           }
       }
       this
   }

그러면 다음과 같이 바뀝니다.

세 번째 예에서는 XML 또는 Markdown과 같은 다른 언어를 삽입하는 방법을 보여줍니다. 아래의 경우에는 세 단계가 있는 절차를 삽입합니다.

xml("""
    
        1단계
        2단계
        3단계
    
""")

결과는 다음과 같습니다.

물론 마크업으로 작성하는 것만으로는 그다지 획기적이지 않습니다. 그러면 좀 더 혁신적이고 흥미진진한 내용으로 넘어가 보겠습니다.

데모

우선, 특정한 구현이 아니라 접근 방식을 보여 드리려고 합니다. 아래 데모는 사용자 지정 XML 마크업을 사용하여 수행되지만 AsciiDoc, Markdown, reStructuredText, LaTeX와 같은 다른 형식을 HTML 또는 .docx에 연결할 수 있습니다.

이 접근 방식이 가진 세 가지 주요 장점

관심 부분의 분리

내용과 표현의 분리는 수없이 논의되어 온 주제입니다. 이 접근 방식은 CSS 초창기부터 웹 개발 분야에 있어 왔으며, 이후 경량 마크업 언어에서 재해석되고 강화되었습니다. 이 기술은 문서의 시각적 및 디자인적 측면을 내용 및 구조와 분리하는 것과 관련이 있습니다. 이러한 방식으로 라이터는 표현을 쉽게 조정하면서 내용에 집중할 수 있습니다.

여기에서 더 나아가 표현에서 데이터를 분리할 수도 있습니다. 설명되는 내용과 직접적인 관련이 없는 마크업으로 세상을 설명하는 것이 아니라, 데이터 자체를 기반으로 문서를 생성할 수 있습니다. 애플리케이션 런타임에서 데이터를 가져온 다음, 해당 표현을 정의할 수 있습니다.

또한, 데이터 디자인에 따라 표현을 조건부로 만들 수 있습니다.
예를 들어, 메서드 설명에 해당 메서드가 사용되지 않는 것으로 표시된 경우, 이를 경고 요소로 전환합니다. 다른 경우에는 단락으로 바꿉니다.

코드를 보면 다음과 같습니다.

val descriptionTag = if (method.description.contains("DEPRECATED")) "warning" else "p"
xml(
   """

Method type: ${method.type.uppercase()}

    
        
            ${method.description}
        
    
   """
)

완전히 새로운 차원의 Docs-as-Code

종종 문서를 코드로 취급하는 것에 대해 이야기할 때, 이는 보통 가벼운 마크업 작성, 문서의 버전 관리, 코드 검토 및 linter 사용과 같은 제한된 범위의 도구와 작업을 의미합니다. 그러나 개발 쪽에서 가져올 수 있는 부분은 훨씬 더 많습니다.

Kotlin DSL을 사용하면 문서가 코드와 동의어가 되어, 라이터가 개발자들이 일반적으로 사용하는 방식을 활용할 수 있습니다. 몇 가지 방식을 보자면 다음과 같습니다.

• 내용의 특정 부분을 모듈로 만든 다음, 다양한 문서 세트에 종속성으로 가져옵니다(예: 일부 프런트엔드 구성 요소 또는 저작권이나 라이선스 계약과 같은 법적 정보).
• 프로그래밍에서 함수 합성(function composition)을 사용하면 복잡한 마크업 구조와 패턴을 더 단순한 단위로 분해하여 소스를 더 세분화하고 유지 관리와 재사용하기 쉽게 만들 수 있습니다.
• 의미론 및 프런트엔드 구성 요소를 타입으로 취급하면 필요한 부분에서 객체 지향 프로그래밍의 이점을 활용할 수 있습니다.

확장성

DSL의 확장성은 혁신적입니다. 사용자 지정 요소를 추가할 수 있을 뿐만 아니라 DSL 자체를 수정할 수도 있어 무한한 가능성이 열립니다.

상상력만이 한계를 짓습니다. 컴퓨터에서 가능한 것은 무엇이든 문서로 가능합니다!

기존 JVM 라이브러리와의 원활한 통합 덕분에 데이터 소스를 통합하고, 내용을 분석 및 보완하며, Selenium 및 Cucumber와 같은 외부 도구 및 프레임워크와 통합할 수도 있습니다.

Kotlin DSL로 가능한 확장의 몇 가지 예를 들면 다음과 같습니다.

• XML, JSON, YAML, 사용자 지정 직렬화 형식, 심지어 애플리케이션 런타임의 객체를 포함한 모든 데이터 형식을 분석하고 통합합니다.
• 매핑을 추가하고 추가 내용으로 문서를 보완합니다.
• 가독성 분석 도구 및 Apache OpenNLP와 같은 라이브러리를 사용하여 자연어를 처리합니다.
• 자동 생성된 부분에 테스트 및 어설션을 적용합니다.

Kotlin의 강점

코드에서 HTML을 생성하려는 시도는 이전에도 있었던 만큼, 문서 용도로 Kotlin을 선택한 이유가 궁금할 수 있습니다.

우선, Kotlin에는 Kotlin를 기반으로 강력한 DSL을 쉽게 만들 수 있는 고급 기능들이 있습니다.

둘째, Kotlin은 실용성과 초보자 친화적인 특성으로 잘 알려져 있습니다. Kotlin은 초보자도 빠르고 쉽게 언어를 이해할 수 있도록 일상 작업을 단순화하는 것을 원칙으로 삼고 있습니다.

예를 들어 초보자가 Kotlin으로 기본적인 ‘Hello, World!’ 프로그래밍을 작성할 때 이해하지 못하는 개념과 키워드로 작업할 필요가 없습니다.

다음은 Kotlin과 Java로 작성한 동일한 ‘Hello, World!’ 프로그래밍을 비교한 예입니다.

Java:

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

Kotlin:

fun main() = println("Hello, World!")

Kotlin에서는 클래스를 정의하거나 public static void 시그니처를 사용할 필요가 없습니다. main() 함수가 진입점 역할을 하며, println()을 직접 사용하여 원하는 메시지를 출력할 수 있습니다. Kotlin의 주요 이점 중 하나인 이러한 단순성 덕분에 기본적인 프로그램을 더 쉽고 즐겁게 작성할 수 있습니다.

앞에서 언급했듯이 Kotlin은 JVM 에코시스템과 원활하게 통합됩니다. Java는 30주년을 맞이할 정도로 오래되었기 때문에 그동안 만들어진 유용한 도구와 라이브러리도 엄청나게 많습니다. 빌드 스크립트에 한 줄만 추가해도 이러한 도구를 워크플로에 통합할 수 있습니다.

Kotlin을 선택한다는 것은 단순함과 강력한 기능이 잘 조화를 이루어 개발자가 즐겁고 효율적으로 작업할 수 있는 언어에 중점을 둔다는 것입니다.

Kotlin DSL을 사용하기 위해 코더가 되어야 하나요?

라이터들이 이렇게 말하는 것을 종종 듣습니다. “저는 개발자나 슈퍼 기술자가 아닌 평범한 테크니컬 라이터입니다! 이것을 어떻게 사용할 수 있나요? 활용하려면 어느 정도의 프로그래밍 능력이 필요한가요?”

DSL 요소를 마크업으로 사용하는 데에는 코딩 기술이 전혀 필요하지 않으며 DSL이 어떻게 작동하는지 알 필요도 없습니다.

일부 자동화와 관련된 작업이 있는 경우에만 Kotlin에 대한 기본적인 이해가 필요합니다. JetBrains Academy의 Kotlin Core 과정이면 여러분이 알아야 할 지식을 충분히 습득할 수 있습니다.

물론, 처음에 Kotlin DSL 학습에 투자하면 장기적으로 보탬이 될 것으로 생각합니다. 직관적인 구문과 IDE 지원을 통해 라이터들은 빠르게 능숙해지고 강력한 문서 도구의 이점을 활용할 수 있게 될 것입니다.

이 접근 방식을 문서 워크플로에 통합하기 위해 약간의 프로그래밍을 배워야 할 수도 있습니다. Kotlin DSL을 작업에 통합하는 과정에서 해당 문서 작업에 맞춤화된 방식으로 실용적이고 흥미롭게 프로그래밍을 배울 수 있습니다. 어쨌든 테크니컬 라이터에게는 가상 수업에서 점수를 계산하거나 기본 계산기를 만드는 것과 같은 인위적인 연습보다 문서와 관련된 작업이 더 즐거울 테니까요. 또한 Kotlin을 배우면 다른 언어와 에코시스템을 이해하는 데도 도움이 됩니다.

이 접근 방식이 모든 테크니컬 라이터의 공감을 얻지 못할 수는 있지만 개발자 도구에 대한 문서를 작성하는 사람들에게는 기술을 향상시키는 귀중한 방법이 될 수 있습니다.

결론

문서용 Kotlin DSL은 패러다임의 전환을 도입하여 테크니컬 라이터가 프로그래밍 언어의 강력한 기능으로 매력적인 내용을 쉽게 작성할 수 있게 해줍니다. Kotlin의 장점, IDE 지원 및 DSL 고유의 확장성을 활용하면 문서는 페이지에 적힌 단순한 단어 그 이상의 가치를 지니게 됩니다. 이는 개발 프로세스에 역동적으로 녹아들어 협업을 강화하고 탁월한 결과로 이어지게 됩니다.

그렇다면 자신의 문서 요구 사항을 해결하기 위해 Kotlin DSL의 가능성을 살펴보는 것은 어떨까요? 

🚀 Kotlin DSL 사용을 시작하려는 분들을 위해 샘플 프로젝트를 준비했으니 다운로드하여 사용해 보세요. 이와 관련하여 질문이 있는 경우 Slack에 마련한 전용 채널인 #kotlin-dsl-for-docs에 글을 남겨주세요.

코드가 가진 힘을 이용해 문서를 새로운 차원으로 끌어 올리세요.

즐겁게 문서를 작성하고 코딩하세요!

게시물 원문 작성자