기술서를 한 권 썼다

이 블로그는 Recruit Engineers Advent Calendar 2020 25일째 글입니다.
메리 크리스마스.네.
마침 어제가 마감일이어서 기술 서적에 출판된 책의 제작이 끝났습니다. 이 블로그는 최근의 기술서의 환경을 정리했습니다. 여러분도 끊임없이 기술서를 통해 기술을 수출하여 떠들썩하게 만들어야 합니다!나는 이런 상황을 시험해 보고 싶다.
올해 GCP와 구름계의 보도는 봉인...

자이언트의 어깨 위에 서다

당신은 졸업 논문, 논문, 학술 논문을 쓴 추억이 있습니까?저 있어요.나는 Tex의 기법을 기억하면서 LaTex 환경을 정리하면서 Eclipse로 쉴 새 없이 지껄인 것을 기억한다.나의 동기생은 마이크로소프트 워드에서 전각과 반각 공간을 이용하여 판면 디자인을 만들면서 매번 수정할 때마다 프로젝트의 번호와 그림의 번호를 수동으로 수정하고 폭사한 것을 기억했다.서로 다른 동기에 텍스트 편집기에서 열심히 편집을 했지만 맥의 하드디스크가 죽었고 백업도 없었다. 이런 일은 지금도 그리운 추억이다.
당신도 이런 고생을 겪으면서 좋은 추억을 갖게 되면 어느새 책과 논문을 쓰는 데 상당한 저촉이 되겠죠.하지만 요즘은 기술서를 쓰는 환경이 유난히 빠르고 편안하게 발전하고 있다.
구체적으로 말하면

Git(GitHub)

prh

디지털 출판 도구 Re: VIEW

선인의 지혜와 지식이 담긴 모든 틀

선인의 지혜와 지식이 담긴 모든 포장

그러면 스트레스 없이 글쓰기에 집중할 수 있다.

환경 구조

필요한 것을 준비하다

금번

macOS Big Sur(11.1)

Visual Studio Code(1.52.1)

탭
편집은 모두 가능하지만 간단히 prh를 사용하는 관점에서 Visual Studio Code를 사용하여 설명합니다.

prh 설치

prh는 교정을 돕는 프로그램 라이브러리입니다.교정 규칙에 따라 규칙을 위반하면 나에게 통지할 것이다.

npm로 각종 도구를 간단하게 설치할 수 있습니다.
sh

npm install -g prh

sh

npm install -g prh-languageserver

그런 다음 설치전문가용 Visual Studio Code용 extension

선인의 지혜와 지식을 모두 담은 템플릿 fork clone

TechBooster/ReVIEW-Templatefork 후 현지 환경git clone에 들어갑니다.

선인의 지혜와 지식이 담긴 모든 것을 용기에 담다

sh

docker pull vvkame/review:5.0

이렇게 준비하면 완성!쓰기만 남았다.

그러면 한번 써볼게요.

혹시 TeX 같은 걸로...?

결국 TeX를 사용하겠지만 거의 인지하지 못했다.그리고 TeX 기법으로는 쓰지 않습니다.익숙한 Mardown과 비슷한 Re:VIEW 기법으로 쓰다.

Re: 이른바 VIEW

Re: 이른바 VIEW
Re:VIEW는 전자책과 종이책에 사용되는 간결하고 강력한 디지털 출판 도구이다.컴퓨터책 등 기술서적(종이·전자)에 쓰이는 상업출판과 동인출판.
https://reviewml.org/ja/
그렇습니다.Re:VIEW를 사용하기 위해 독자적인 기법을 사용하지만, Mardown에 익숙해진 사람은 어렵지 않게 공부할 수 있습니다.여기서 기법을 확인할 수 있다.

아무튼 해보세요.

배우는 것보다 배우는 것이 낫다. 어쨌든 한번 해 보자.
먼저 Visual Studio Code를 사용하여 fork를 연 후 clone 템플릿의 루트를 엽니다.
각양각색의 파일이 있지만 기본적으로 편집해야 하는 파일은 세 가지뿐이다.

articles/*.re

본문을 구성하는 문서군.각 장은 파일을 만듭니다.

articles/catalog.yaml

이것은 각 장의 파일을 어떤 순서로 배열해야 하는지를 설정하는 데 사용되는 파일이다.
템플릿에서
yaml

PREDEF:
  - preface.re

CHAPS:
  - article.re

APPENDIX:

POSTDEF:
  - contributors.re

이렇게 쓰여 있지만 보기만 해도 알 수 있다.

articles/config.yaml

이것은 여러 가지 설정을 할 파일입니다.
템플릿에 섬세한 주석이 있기 때문에 주석을 어떻게 쓰는지만 보면 일목요연하다.

책을 써 보다

그렇다면 먼저 템플릿을 유지하고 PDF를 실제 출력해 감동을 주자.
Terminal을 열고 템플릿 경로의 build-in-docker.sh를 실행합니다.
시간이 좀 지나서 articles/ 디렉터리 아래에서 출력하고 싶습니다ReVIEW-Template.pdf.열어보세요. 이렇게 간단한데 이걸 출력할 수 있어요!?!?!?깜짝 놀랐어요.

prh로 자동 교정

만약 상술한 절차가 정확하게 진행된다면, 나는 이미 자동 교정을 진행하고 있다고 생각한다.교정 규칙 정의 파일은 prh-rules/ 디렉터리 아래에 존재하며 필요에 따라 편집됩니다.

책을 쓸 때 어떤 절차로 써야 합니까

혼자 썼으면 적당히 진행했으면 좋겠죠.하지만 여러 사람이 쓸 때는 누구와 쓰느냐에 따라 절차를 고려한다.

전원 엔지니어의 경우

코드 써.GiitHub을 사용한 버전 관리, 리뷰, 하고 싶으면 GiitHub Actions 설정

전원이 엔지니어가 아닌 경우

전체 인원은 Re:VIEW를 사용하지 말고 먼저 Google Docs 등으로 글을 쓰고 서로 논평하세요.그리고 원고를 제출한 후에 가능한 사람은 각종 도구로 교정하여 Re:VIEW 기법으로 수정하여 PDF를 출력한다.
다른 사람에게 새로운 것을 배우게 하기보다는 원고를 쓰는 데 집중하라.너 자신도 교수법과 GiitHub의 사용법에 힘을 쓰지 말고 원고를 쓰는 데 집중해야 한다.

실제로 책을 써 보다

이제야 이런 블로그를 쓰게 되었는데, 나는 이번에 처음으로 집필하고, 처음으로 전시회에 나왔다.
최근 기술서적전도 마찬가지다. 이 블로그의 주인 젠(Zenn)에게도 책을 판매하는 기능이 있어 글을 쓸 기회가 높아지고 있다.
부랴부랴 블로그를 쓰거나 어떤 무대에 오를 때도 있지만, 실제로 책을 쓰고 느낀 소감을 적어 정리하고 싶다.

어느 정도 통일된 성과를 얻을 수 있다

이 블로그는 이미 갈수록 길어지고 있지만, 책의 격식이기 때문에 몇 십 페이지의 양을 단숨에 출력할 수 있다.구성을 생각하면서 단위의 지식을 망라하는 점이 매력을 느꼈다.

합작하여 집필할 수 있다

무언가를 완성할 때, 나는 거의 한 사람이 완성한 것이 없다고 생각한다.내가 이번에 쓴 책의 내용도 몇 사람이 완성한 것이다.다른 매체의 경우 분량과 형태를 볼 때 협업 수출은 매우 어렵지만 분담장, 자신이 맡은 일을 먼저 쓰고 구성하는 간단한 결정으로 협업으로 성과를 낼 수 있다.당연히 당연한 것이지만 단순히 감동했다.

사회적 피드백을 줄 수 있어요.

유명한 플랫폼에 오르면 더 많은 사람들이 그 성과를 볼 수 있고 피드백의 기회를 늘릴 수 있다.물론 책이 잘 팔리는 돈이거나 트위터의 DM일 수도 있다.
피드백을 받을 수 있는 것은 매우 귀중한 것이다. 이 기회를 늘리기 위해 전방위적인 수출은 매우 중요하다.전혀 그렇지 않다면 어떻게 할까...

총결산

선인의 지혜와 지식에 따라 책을 아주 간단하게 출력할 수 있다

정리 작문 환경도 간단

책의 격식은 블로그와 다른 매력을 가진다

적극적으로 수출하여 피드백을 받을 기회를 증가합니다!

그럼 내년에 봐요!

Special Thanks