문서 작성 문제

아래 그림은 거석진으로 세계에서 가장 유명한 건축 유적지 중의 하나입니다!

© 2007 by thegarethwiscombe

거석진을 들어보지 못한 사람을 찾기는 어렵지만, 거석진을 만든 옛사람들이 추구했던 최초의 목적이 무엇인지 확신하는 사람은 없다.사실 이 기념비의 건설자가 어떤 문자나 도형 묘사를 제공한다면 과학자들은 감격해 마지 않을 것이다.
코드 라이브러리의 '거석진' 을 언급할 때, 그것은 우리가 매일 사용하는 위대한 구조 해결 방안일 수도 있고, 그 위에 완전한 시스템을 구축할 수도 있으며, 우리나 이전의 개발자들이 왜 그들처럼 그것을 구축했는지 진정으로 이해하지 못할 수도 있다.어쩌면 그들은 나름대로의 이유가 있을지도 모르지만, 지금은 전혀 중요하지 않다.우리는 확신할 수 없다.
그러나 특정 원소를 실현하는 원시적인 원인에 대한 이해가 부족하면 복잡성이 간혹 증가할 수 있다.

파일의 중요성

많은 개발자들이 양호한 문서를 가진 프로젝트를 제작하고 사용하는 것을 좋아하지만, 그들은 여전히 문서를 작성하고 싶지 않은 경향이 있다.비록 우리 개발자들은 문서의 중요성을 이해하지만, 이러한 상황의 모순은 여전히 존재한다.그럼에도 불구하고, 코드를 작성하고 지원하는 상세한 설명의 어려움은 확실히 그 부담을 짊어졌다.그런데 더 쉽게 만들 수 있는 방법은 없을까요?내 생각에는 그렇다!본문에서 보여드릴게요!

문헌 창작의 주요 문제

주요 문제는 코드와 문서의 분리일 수도 있다.우리가 서로 다른 시스템(예를 들어 GitHub과Confluence)에서 코드와 문서를 작성할 때 우리는 두 가지 다른 코드와 문서 버전 제어 시스템이 있다.그러나 이것은 무엇을 의미하는가?그것은 프로젝트 지원의 복잡성을 증가시킬 것이다.예를 들어 원본 코드의 모든 변경 사항은 수동으로 문서와 동기화해야 하고 문서의 모든 변경 사항은 원본 코드에 연결해야 한다.
이런 복잡성은 종종 사람들이 문서를 작성하는 것을 막을 수 있다. 그들은'왜 우리는 개발 상태에 있는 프로젝트를 위해 문서를 작성하는 데 시간을 들여야 합니까?'라고 물어볼 수도 있다."우리가 완전한 제품을 얻었을 때, 우리는 문서를 작성할 것이다."를 추가합니다.이것은 가능하지만 불행하게도 현실 생활에서'완성'의 프로젝트는 죽음의 프로젝트이다.모든 현장 프로젝트는 지속적인 개발 상태에 있다.따라서 좋은 문서를 가지고 있는 유일한 방법은 개발과 병행하여 작성하는 것이다. 최소한의 비용으로 이 과정을 가능한 한 간단하게 하는 것이다.
이를 예로 들면 서로 다른 시간과 장소에서 개발자가 이 문제를 해결하려고 시도한다.예를 들어 Racket 언어는 Scribble을 사용하여 소스 코드와 문서를 최대한 가깝게 만들 수 있는 나름의 방법이 있습니다. 이를 통해 문서의 평가를 포함하여 Racket 코드를 통합할 수 있습니다.

#lang scribble/manual
@(require (for-label racket))

@title{My Library}

An example of the Racket code:

@racketblock[

(define (nobody-understands-me what)
  (list "When I think of all the"
        what
         "I've tried so hard to explain!"))
(nobody-understands-me "glorble snop")

]

또 다른 예에서 만약에 Emacs 애호가라면 Org Mode이라는 훌륭한 도구/언어를 사용할 수 있습니다. 복잡한 문서를 작성하고 서로 다른 프로그래밍 언어의 원본 코드를 평가하며 Literate Programming의 예를 들어 모든 원본 코드를 문서에 저장할 수 있습니다.다음은 홈 페이지의 예입니다.

#+title:  Example Org File
#+author: TEC
#+date:   2020-10-27

* Revamp orgmode.org website

The /beauty/ of org *must* be shared.
[[https://upload.wikimedia.org/wikipedia/commons/b/bd/Share_Icon.svg]]
** DONE Make screenshots
   CLOSED: [2020-09-03 Thu 18:24]

** DONE Restyle Site CSS

Go through [[file:style.scss][stylesheet]]


** TODO Check CSS on main pages 

* Learn Org

Org makes easy things trivial and complex things practical.

You don't need to learn Org before using Org: read the quickstart
page and you should be good to go.  If you need more, Org will be
here for you as well: dive into the manual and join the community!

** Feedback

#+include: "other/feedback.org*manual" :only-contents t
* Check CSS minification ratios

#+begin_src python
from pathlib import Path
cssRatios = []
for css_min in Path("resources/style").glob("*.min.css"):
    css = css_min.with_suffix('').with_suffix('.css')
    cssRatios.append([css.name,
    "{:.0f}% minified ({:4.1f} KiB)".format( 100 *
                      css_min.stat().st_size / css.stat().st_size,
                      css_min.stat().st_size / 1000)])
return cssRatios
#+end_src

#+RESULTS:
| index.css    | 76% minified ( 1.4 KiB) |
| org-demo.css | 77% minified ( 2.8 KiB) |
| errors.css   | 74% minified ( 4.9 KiB) |
| org.css      | 75% minified (10.7 KiB) |

만약 당신의 팀이 조직 모델과 Emacs에 익숙하다면 조직 모델은 좋은 해결 방안입니다.심지어 Github는 조직 모드를 지원하기 때문에 *.org 파일이 아닌 *.md 파일을 사용할 수 있습니다.
다른 한편, 코드와 문서의 분리가 가져온 또 다른 문제는 코드와 문서 부분 간의 내집성이 약하다는 것이다.예를 들어, 우리는 시스템에서 하나의 기능을 묘사할 수 있지만, 묘사된 모든 부분은 원본 파일의 다른 부분과 관련이 있다.이 문제로 인해 원본 코드와 연결된 파일을 변경하거나 원본 파일의 특정 부분을 편집한 후에 문서의 일부분을 업데이트할 수 없습니다.반대로 문서를 읽을 때 특정한 단락의 문서와 관련된 소스 코드를 신속하게 찾기 어렵다.만약 이 문제를 해결하지 않는다면, 문서 지원의 복잡성은 프로젝트 규모가 증가함에 따라 증가할 것이다.
그러나 당신은 동의하지 않을 수도 있습니다. "그것은 사실이 아닙니다. 우리의 API 문서에는 이런 문제가 없습니다."네가 옳다!API 문서나 스토리북 문서에는 소스 코드로 생성되거나 소스 코드가 대량으로 참여하기 때문에 이런 문제가 없을 것이다.그것은 원본 코드와 매우 강한 내중성을 가지고 있으며, 원본 코드와 같은 버전 제어 시스템을 사용한다.프로젝트 문서를 쉽게 작성할 수 있는 유일한 방법은 코드를 작성하는 것과 같은 도구 모음을 사용하는 것이다.
여전히 Scribble이나 Org Mode 등의 도구를 사용하여 이 문제를 해결할 수 있지만, 문서의 다른 부분을 수동으로 조합해야 하기 때문에 대형 프로젝트에서는 어려울 수 있습니다.

코드로 된 문서

문서와 코드를 함께 놓으면 변경 사항을 더욱 잘 제어하고 문서 지원을 더욱 쉽게 할 수 있다.그러나 적합한 도구가 없으면 개발자를 제외한 누구도 문서를 사용하기 어렵다.예를 들어 우리는 가격 인하 파일을 사용하여 문서를 작성할 수 있지만, 만약 우리가 그것들을 관련 원본 파일 근처에 두면 매니저, 분석가, QA, 디자이너가 문서에서 일부 내용을 찾기 어려울 것이다.다른 한편, 만약 우리가 그것들을 구조를 가진 단독 디렉터리에 두면, 우리는 내중성이 비교적 약한 문제를 해결할 수 없을 것이다.또한 태그 파일을 사용하면 *.md 파일에서 원본 파일의 특정 부분에 대한 인용을 자동으로 만들 수 없거나 전체 기능에 대한 모든 *.md 파일을 자동으로 조합할 수 없지만 원본 파일의 측면에서 작성할 수 없습니다.다음 예를 살펴보겠습니다.

.
└── src
    ├── api
    │   ├── auth.js
    │   ├── news.js
    │   └── offers.js
    ├── components
    │   ├── auth.js
    │   ├── header.js
    │   ├── news.js
    │   └── offers.js
    ├── index.js
    └── reducers
        ├── auth.js
        ├── news.js
        └── offers.js

이 예는 간단한 프로젝트를 보여 주었다.만약 우리가 auth 기능을 위해 문서를 작성하려고 한다면.전체 기능은 세 개의 다른 파일에서 이루어지지만'auth의 실현'을 통해 모든 원본 파일은 api/auth.js 또는 components/auth.js이 아니다.따라서 코드와 문서 사이에 강력한 내집을 실현하기 위해 우리는 신분 검증에 관한 문장의 다른 부분을 서로 다른 파일에 놓고 이런 부분에서 문장을 만들어야 한다.
만약 우리가 이 점을 해냈다면, 더 좋은 것은 우리가 생성한 글의 원본 코드에 링크를 추가했기 때문이다. 우리는 약한 내부 집합과 서로 다른 버전 제어 도구를 사용하여 이 두 문제를 해결할 수 있다.좋은 문서는 검색하고 편집할 수 있도록 허용해야 하기 때문에 사용하기가 좀 어색합니다.

솔루션

나는 이 모든 문제를 해결할 수 있는 방법을 찾으려고 시도했지만 불행히도, 나는 찾지 못했다.그래서 저는 모든 묘사의 목표를 실현하기 위해 Fundoc의 도구를 썼습니다. 심지어 더 많습니다.이 도구는 다음을 수행할 수 있습니다.

은 가능한 한 문서와 원본 코드를 저장합니다.

은 코드와 같은 버전 제어 시스템을 사용하여 문서를 작성한다.

은 언어불가지론자일 것이다.

은 특정 위치의 다른 저장소에서 모든 문서를 수집합니다.

은 비프로그래머가 문서를 읽고 쓸 수 있도록 허용한다.

그럼 펀독은 뭘 할 수 있을까요?그것은 두 가지 형식의 문서를 만들 수 있다. 원시 가격 인하 파일 (아마도 이따가 조직 모드 지원을 추가할 것) 과 mdBook.이 도구 배후의 주요 사상은 가능한 한 간단명료하게 사용하고 필요한 모든 기능을 제공하는 것이다. 예를 들어 문서 검색, 프로젝트 구조를 알 필요가 없는 상황에서 문서 편집, 버전 제어 시스템 사용 등이다.

그러나 나는 무엇으로 도구의 단순성을 유지하고 비프로그래머를 위해 사용할 가능성을 유지해야 합니까?나는 Github을 사용한다. 바로 이렇다.물론 앞으로 GitLab, Bitbucket 등 다양한 서비스에 대한 지원을 확대할 수 있을 것이다.어떻게 일하는지 설명해 드릴게요.개발자는 소스 또는 태그 파일에서 문서를 작성하고 결과 글의 제목을 설명하는 간단한 태그로 각 문서 섹션을 표시합니다.

// src/api/auth.js

/**
* @Article Authentication
*
* To get authenticated, you should use the `login` function, which returns auth-token to pass it with API requests that require authentication.
*/
const login = (username, password) => {
    // some code here
}

/**
* @Article Authentication
* 
* To log out, use the `logout` method. It will invalidate the auth-token and delete it from cookies.
*/
const logout = () => {
    // some code here
}

UI 부품에 대한 설명은 다음과 같습니다.

// src/components/header.js

const Header = props => {
    const { isUserAuthorized } = props

    /**
    * @Article Authentication
    *
    * Only authorized users can see their balance in the header
    */
    return (
        <div>
            ...
            {isUserAuthorized && <UserBalance />}
            ...
        </div>
    )
}

이 간단한 예는 태그 파일로 컴파일됩니다.

# Authentication

To get authenticated, you should use the `login` function, which returns auth-token to pass it with API requests which require authentication. [[~]](https://github.com/username/repository/blob/master/src/api/auth.js#L3-L7)

To log out, use the `logout` method. It will invalidate the auth-token and delete it from cookies. [[~]](https://github.com/username/repository/blob/master/src/api/auth.js#L12-L16)

Only authorized users can see their balance in the header. [[~]](https://github.com/username/repository/blob/master/src/components/header.js#L6-L10)

To see more realistic documentation examples you can check out documentation of Fundoc itself or another project that used Fundoc.

컴파일된 태그 파일에서 원본 코드의 특정 부분에 대한 인용을 볼 수 있습니다.이것은 문서의 모든 부분의 정확한 출처를 찾을 수 있도록 합니다.만약 프로그래머가 문서를 편집하려고 하지 않는다면, 그것은 매우 유용할 것이다.만약 그들이 여전히 git와 협력해서 그들의 변경을 추진해야 한다고 생각한다면, 그들은 실제로 이렇게 해서는 안 된다.다음은 Fundoc 저장소에서 문서를 편집하는 예입니다.

그래서gif에서 우리가 문서를 편집해야 하는 유일한 것은GitHub 자체임을 알 수 있다.그렇습니다. GitHub이 무엇인지, 제출, 지점 등 기본 용어를 이해해야 합니다.실천은 QA, 매니저, 디자이너, 분석가가 문제 없이 그것을 처리할 수 있음을 나타낸다.또한 이런 문서 처리 방식은 비개발자로부터 프로젝트의 파일 구조를 이해할 필요가 없다.이것은 CLI 도구를 사용하는 것보다 훨씬 쉽고, 합류와 소스 코드를 동기화하는 것보다 훨씬 쉽다.
본고의 마지막 부분에서 Fundoc는 현재 테스트 상태에 있고 일부 API는 장래에 변화가 발생할 수 있음을 여러분에게 일깨워 주고 싶습니다.그렇지 않으면, 그것은 이미 많은 문제를 해결하고, 다른 항목에서 사용되기 때문에, 당신도 그것을 사용해 보실 수 있습니다.질문이나 조언이 있으면 언제든지 Github 또는 PRs를 통해 보내 주십시오.나는 너의 도움 아래 더욱 잘 할 수 있어서 매우 기쁘다.