文書作成の問題点

下の写真はストーンヘンジ、世界で最も有名な建築記念碑の一つです!

© 2007 by thegarethwiscombe

ストーンヘンジを聞いていない人を見つけるのは難しいですが、誰もがそれを構築した古代の人々によって追求された元の目的は何かを確認することができます.実際には、科学者は、この記念碑のビルダーから任意のテキストやグラフィカルな説明に感謝するだろう.
CodeBaseの“StoneHenges”になると、それは私たちが毎日使用して、私たちまたは以前の開発者は本当に彼らがやったように構築を理解せずにその上に全体のシステムを構築する素晴らしいアーキテクチャのソリューションにすることができます.おそらく、彼らには理由がありました、しかし、これらは現在完全に無関係です.私たちには確信が持てません.
しかし、特定の要素を実装することの背後にある最初の理由についての理解の欠如は複雑さの時折増加につながることができます.

ドキュメンテーションの重要性

多くの開発者は本当に良いドキュメントを持っているプロジェクトを作成し、作業を楽しむが、彼らはまだそれを書いて消極的に感じる傾向がある.状況のこのパラドックスは私たち、開発者、ドキュメントの重要性を理解しています.それでも、コードの詳細な記述を書いて、支持することの難しさは、その負担を負担します.しかし、それを簡単にする方法がありますか?私は思う!この記事であなたにお見せしましょう!

文書作成の主な問題

主な問題は、おそらく、問題の残りのルートはコードとドキュメントの分離です.異なるシステム(例えばGithubとConfluence)でコードとドキュメンテーションを書くとき、我々はコードとドキュメンテーションのために2つの異なるバージョン管理システムを持っています.しかし、これはどういう意味ですか?よく、それはプロジェクトのサポートの複雑さの成長につながることができます.たとえば、ソースコードのすべての単一の変更を手動でドキュメントと同期する必要がありますが、ドキュメント内のすべての変更は、ソースコードに接続することです.
この複雑さによって、人々がドキュメントを書くのを止めることがしばしばあります.「開発状況におけるプロジェクトのドキュメントを書くために、なぜ我々は時間を費やすのでしょうか?」加えて、「完成した製品を得るとき、ドキュメンテーションを書きます」.これは可能ですが、残念ながら、実際の生活では、“完了”プロジェクトは、デッドプロジェクトです.すべてのライブプロジェクトは継続的な開発状態にあります.このように、良いドキュメンテーションを持つ唯一の方法は開発と並行してそれを書くことです.
たとえば、これは別の時間と異なる場所で、開発者はこれを解決しようとした.例えば、ラケット言語は、Scribbleを使用してソースコードとドキュメントをできるだけ近くに保つ独自の方法を持っています.

#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) |

あなたのチームがorgモードとemacsに精通しているならば、orgモードは素晴らしい解決です.Githubはorgモードをサポートしており、*.orgの代わりに*.mdファイルを使用できます.
他方、コードとドキュメンテーションの分離に起因するもう一つの問題はコードとドキュメンテーション部分の間の弱い結合です.例えば、私たちのシステムの機能を記述することができますが、説明のすべての部分は、ソースファイルの異なる部分についてです.この問題は、ソースコードに接続されたファイルを変更したり、ソースファイルの特定の部分を編集したりした後に、ドキュメントの特定の部分を更新することができません.逆に、ドキュメントを読んでいる間、ドキュメントのある段落に関連するソースコードをすばやく見つけることは難しい.この問題を解決することなく、ドキュメントのサポートの複雑さは、プロジェクトのサイズの成長とともに増加するでしょう.
しかし、私たちのAPIドキュメントにはそのような問題がありませんそして、あなたは正しいよ!ソースコードやソースコードの巨大な関与によって生成されるので、APIドキュメントやストーリーブックのドキュメントに問題はありません.ソースコードとの強力な結合力を持ち、ソースコードと同じバージョン管理システムを使用します.プロジェクトドキュメントを簡単に書くための唯一の方法は、コードライティングと同じツールセットを使用することです.
Scribbleやorgモードのようなツールでこの問題を解決することができますが、手動でドキュメントを作成する必要があります.

コードとしてのドキュメント

ドキュメントとコードを一緒に保つことは、変更のより良い制御を達成し、ドキュメントのサポートを容易にすることができます.しかし、適切なツールなしで、それは開発者以外の誰のためのドキュメンテーションとともに働くために厄介なことがありえます.たとえば、ドキュメントを書くためにMarkdownファイルを使用することができますが、関連するソースファイルの近くに配置すると、管理者、アナリスト、QAS、デザイナーがこのドキュメントで何かを見つけるのは難しいでしょう.一方、構造体を別のディレクトリに配置すると、弱結合の問題は解決しません.また、Markdownファイルを使用すると、自動的に*.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機能のためにドキュメンテーションを書きたいと思いましょう.全体の機能は、3つの異なるファイルで実装されていますが、“Authの実装”、すべてのソースファイルではなく、api/auth.jsまたはcomponents/auth.js.したがって、コードとドキュメントの間の強力な結合を達成するために、私たちは、どうにか、異なるファイルの認証に関する記事の異なる部分を配置して、これらの部分から一つの記事を生成しなければなりません.
我々がそうするならば、さらによりよく、我々は生成された記事からソースコードへのリンクを加えます、我々は弱い結束による両方の問題を解決して、異なるバージョン管理ツールを使用することができます.しかし、良いドキュメントがそれを通して検索して、それを編集するのを許すべきであるので、それはまだ使用するのに少し厄介です.

解決策

私は、これらの問題の全てを解決することができた何かを見つけようとしました、しかし、残念なことに、私はそれを見つけませんでした.それで、私はすべての記述されたゴールとより多くを成し遂げるために、Fundocと呼ばれている私自身のツールを書きました.ツールは次のようになります.

ドキュメントとソースコードをできるだけ閉じます.

コード用のドキュメント用の同じバージョン管理システムを使用します.

言語不可知論.

特定の場所の異なるリポジトリからすべてのドキュメントを収集します.

ノンプログラマがドキュメントを読み書きすることができます.

それで、fundocは何をすることができますか?これは2つの形式でドキュメントを生成することができます:生のMarkdownファイル(後に私はorgモードのサポートを追加します)とmdBook.このツールの背後にある主なアイデアは、ドキュメントを介して検索のような必要な機能のすべてを提供しながら、できるだけ簡単に使用するように非複雑にすることです、ドキュメントの編集を必要とせずに、プロジェクトの構造を知って、1つのバージョン管理システムを使用してなど.

しかし、私はツールの簡単さと非プログラマのためにそれを動作する可能性を保つために使用するか?私は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>
    )
}

この簡単な例は、1つのマークダウンファイルにコンパイルされます.

# 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.

コンパイル済みのMarkdownファイルでは、ソースコードの特定の部分への参照を参照できます.これは、ドキュメントのすべての単一の部分の正確なソースを見つけることができます.ドキュメントを編集したいなら、非プログラマにとって便利です.あなたが彼らがまだ彼らの変化を押すためにgitで働くべきであると思っているならば、彼らは実際にはそうしてはいけません.fundocのリポジトリにおけるドキュメントの編集例です.

GIFでは、ドキュメントを編集する必要があるのは、Github自体だけです.はい、まだGitthubが何であるか、そして、「コミット」と「枝」のような基本的な用語の理解が必要です.プラクティスが示すように、QAS、マネージャー、デザイナー、およびアナリストはどんな問題もなくそれを扱うことができます.同時に、このドキュメントで作業する方法は、非開発者からプロジェクトのファイル構造を知る必要はありません.Confluenceとソースコードを同期させるよりも、CLIツールの操作や劇的に簡単に動作することは間違いない.
記事の最後には、FunDocは今ベータ状態にあることを思い出させたいと思います.さもなければ、それはすでに多くの問題を解決して、異なったプロジェクトで使われます.ご質問やご提案がある場合は、Githubの問題やPRS経由で私を送って自由に感じる.私は喜んであなたの助けを借りてそれを改善するよ!