Excelドキュメントから脱却するために

    2018年、明けましておめでとうございます。
    制作部の里山です。

    年始の社内朝礼で発表した通り、Excelによるドキュメント管理から本格的に脱却することを目指しています。

    理由はExcelだとバージョン管理ができないためです。
    ドキュメントだってGitでバージョン管理すれば、更新履歴をdiffでチェックできればいちいちドキュメント内に書かなくてもいいし、書き忘れて伝達ミスが起こることもなくなりますが、Excelは残念なことにバイナリなのでdiffを取得できません。

    そこで、ドキュメントシステムを使いたいと思っています。ドキュメントに書く内容をコーディングしてビルドすれば、きれいなドキュメントが出来上がるというシステムで、テキスト形式のためバージョン管理も容易です。いちいち更新履歴を書かなくても正しくコミットしていけば変更箇所は明白です。
    ドキュメントシステムは幾つかありますが、Pythonで作られているSphinxがそれなりに有名のようで試してみました。

    ■Sphinxのインストール手順(Windows)

    1.Pythonをインストール。
    2.easy_install sphinxコマンドを実行。

    ■Sphinxの構築手順

    1.適当なディレクトリに移動する。
    2.sphinx-quichstartコマンドを実行。幾つか質問されるので適宜回答する。
     公式サイトによれば最低限autodoc拡張に関する質問だけyesにしてほしいとのこと。
    3.ビルドしたい時はmake htmlコマンドを実行。
     ビルドされた成果物はソースディレクトリ内/_build\htmlのディレクトリに出力されます。

    最低限必要なのはこれだけです。
    あとは、TOCツリーを構築してreStructuredText形式でマークアップしていけばドキュメントを作れます。

    試しに以下のようなドキュメントを作りました。

    以下のようにマークアップしています。reStructuredText形式なのでちょっと癖がありますが、そんなに難しくありません。また、Markdownを導入する方法もあるみたいです(未検証)。

    ========================================================
    101. ログイン画面
    ========================================================
    
    概要
    ========================================================
    
    アプリケーションへのログインを行う画面。IDとパスワードを入力し、ログインボタンを押すと入力値のバリデーションとログインを行う。
    
    画面構成(ワイヤーフレーム)
    ========================================================
    
    .. image:: ../img/screen_login.png
        :height: 400px
    
    画面項目定義
    ========================================================
    
    .. csv-table::
        :header: No,項目名,種類,属性,桁数,必須,フォーマット,備考
        :widths: 1,8,5,3,1,1,5,6
    
        1,ロゴ,画像,,,,,
        2,会員ID,テキストボックス,string,32,○,メールアドレス,
        3,パスワード,テキストボックス,string,32,○,,
        4,ログインボタン,ボタン,,,,,
        5,パスワードをお忘れの方,テキストリンク,,,,,
        6,会員登録はこちら,テキストリンク,,,,,
        7,ご利用ガイド,テキストリンク,,,,,
    
    詳細挙動定義
    ========================================================
    
    初期表示時
    --------------------------------------------------------
    
    1. 会員ID、パスワードをクリアする。
    
    ログインボタン押下時
    --------------------------------------------------------
    
    1. バリデーションを行う。(:ref:`val-login` を参照)
    2. ログインAPIを呼び出す。(:ref:`api-login` を参照)
    3. ログインAPIの結果により、以下の処理を行う。
        3.1. 成功時(STATUS = 200)
            3.1.1. レスポンスに含まれるusertokenをアプリ内に保存する。
            3.1.2. ログイン後トップ画面に遷移する。
        3.2. 失敗時(上記以外)
                3.1.1.1. エラーメッセージ(ID:xxx)を表示する。
    
    バリデーション仕様
    ========================================================
    
    .. _val-login:
    
    ログインボタン押下時バリデーション
    --------------------------------------------------------
    
    .. csv-table::
        :header: No,項目名,バリデーション内容,エラーコード,備考
        :widths: 1,8,15,3,6
    
        1,会員ID,入力されていること。,E_001,
        2,パスワード,入力されていること。,E_001,
    
    
    APIリクエスト仕様
    ========================================================
    
    .. _api-login:
    
    ログインAPIの呼び出し方
    --------------------------------------------------------
    
    * エンドポイント:https://{domain}/v1/login
    * メソッド:POST
    * パラメータ
    
    .. csv-table::
        :header: No,項目名,設定内容,備考
        :widths: 1,8,15,6
    
        1,member_id,会員IDに入力された内容をそのままセットする。,
        2,password,パスワードに入力された内容をそのままセットする。,
    

    Sphinxは上記のようなテキスト形式ですので、このソースコードをGitで管理していけばバージョン管理もしっかりとできます(コミット漏れなどヒューマンミスが無ければ)。
    また、Pythonさえ動けばプラットフォームを選ばずに導入ができます。例えば、SphinxをAWSなどのクラウドに導入してドキュメントサーバーを立てるという方法も取れます。で、CIと連携させてデイリーとかで最新のドキュメントソースを落としてビルドして……という仕組みを作れば常に最新の状態でドキュメントを管理することもできます。さらに、差分があればメールやSlack/Chatwork等でさくっと通知するみたいな仕組みも入れれば更新の伝達漏れも防止できます(コミット漏れなどヒューマンミスが無ければ)。

    ただし、今でもExcel納品が必要なプロジェクトはかなり多いため、プロジェクトを始める前にドキュメントの納品方法を確認しておいたほうが良いでしょう。試したことはありませんが、HTML以外にもPDFやepub形式などいくつかの種類でビルドができるみたいです。

    そういえば、Excel方眼紙のドキュメントだと環境次第で印刷レイアウトがガタガタになってしまいますが、HTMLやPDFであればその心配はほとんどないというのも利点ですね。

    では。


    関連記事

    • 書籍レビュー:この一冊で全部わかるWeb技術の基本

      書籍レビューの2冊目はWeb技術全般に関する読み物です。内容的にはドットコムマスターなどを受験する際にも使えるのではないでしょうか。ITの枠の中に一応長年いる私にとって既知のものが多かったですが、その中でも「あ、これは知らなかった」となったものを数個ピックアップしたいと思います。
      ・マイクロフォーマット
      HTMLやXMLで記述されたWebページの中の記述1つ1つに意味を持たせて、外部のコンピュータが参照してきても自律的に意味がわかるようにしましょうという取り組みです。そういえばXMLという言葉を初めて聞いた時にそんな風になるという話を聞いたのを思い出します。ただマイクロフォーマットで検索しても古い記事ばかりが目につき、Google Trandsでも明らかに話題に上がらなくなってきています。
      ・クエリキャッシュサーバー
      データベースへの検索結果に対する応答をキャッシュするサーバー。メモリ上にそうした結果をキャッシュして応答を早くするという話は聞いたことがありますが、書籍では専用のサーバーを間に立てています。検索するとDNSキャッシュサーバーの事例ばかりが引っかかり、そうしたDB検索キャッシュ専用サーバーの存在についてはなかなか思ったものにたどり着けず。
      ・マッシュアップ
      既存のWebサービスを複数組み合わせて新たなサービスを提供すること。例えば位置情報から周辺のスーパーの特売情報をピックアップして提供したりなど。既存の楽曲から良いとこどりして新しい曲を作る音楽の世界でも使われている言葉だそうです。
      ・WAF(Web Application Firewall)
      アプリケーション通信の中身まで精査するFireWall。クライアントが投げてくるSQLコマンドの中身までチェック、とあったのですごいな!と最初は思いました。しかし、今時ほとんどの通信がSSLで暗号化されているのでどうやって中身を見るのだろう、と調べて見ると。。クライアントからのhttps通信をいったん全てWAFで受け取って内容を精査、その後WAF〜Webサーバー間で改めてhttpで通信するのだそうです。構築と運用が大変そうですね。。
      ・CAPTCHA
      Webサイトのアカウント作成時などに遭遇する、うねうねっと表示されたアルファベットを読み取って入力するあれ。入力者がボットやプログラムではなく人間であることを示すためのあれをCAPTCHAと言うのだそうです。最近だと分割された写真から道路標識/車に該当する枠をクリック選択せよ、というのによく出くわしますが標識ではなくお店の看板とかも混じっていて毎回ちょっと悩まされます。。
      まとめ
      広く浅く記載されており、IT業界に入って日が浅い方に適しているかもしれませんが、それなりに経験年数を積んだ方にも読み物として十分面白いと思います。分かっていたつもりで、間違った理解をしていたものなどが見つかるかもしれません。
      2018/09/02 技術 / デザイン / 制作
    • 書籍レビュー:6ステップでマスターするHTML+CSSデザイン

      はじめに
      こちらのブログへの初投稿は諸事情もあり、やや固く書籍レビューからです。これまでHTMLとかCSSとタイトルについた本を買ってきては延々とタグの紹介とその実演が続き、途中で飽きてしまうのがパターンでした。でもこの書籍はモバイルファーストが叫ばれてから久しいですが、パソコンの他、画面の大きさや縦横比が異なるスマートフォンを意識したページをつくることを前提としており、実際にHTMLやCSSを書いてみても飽きが来ることなく最後まで通せました。(Amazonでの評価も高いようです ↓)
      この本のポイント
      ・最初にページ全体の構成を意識してから作成に入る。
      ・パーツ単位に作成を進めていき、繰り返し出て来るタグも多い。
      リファレンスを見ながら片っ端からタグを試すのではなく、より実践的にパーツ単位に作成を進め、HTML/CSS記述の際には何度も繰り返し出て来るパターンもあり、現場で実際に必要なパターンが頭に定着しやすかったと思います。
      実際にやってみる
      私自身が実際にやってみて体で覚えるタイプなので、気になったところと本書籍の肝と思われる部分だけ実際にやってみました。
      ・Webフォントの利用
      Webフォントについては概念だけは知っていましたが、自身で試したことがなかったのでやってみました。書籍ではGoogle Fontsの利用となっていたのでお手本通りにそのまま。日本語フォントが無いという話を過去に聞きましたがそんなことはなく、ぱっと見で良さげなものもいくつかありました。手順も簡単です。
      1. https://fonts.google.com/ にアクセス
      2. 使ってみたいフォント右上の+(プラス)をクリック
      3. '1 Family Selected'と表示される黒いバー部分をクリック
      4. 表示されるコードの1つ目(link href...)をHTMLファイルのheadタグの中に。2つ目(font-family..)をCSSファイルのフォントを適用したい箇所にそれぞれコピペ。
      手順は以上です。普段フォントの差を意識することのない私でも違いはわかりました。どんなデバイスでアクセスしても常に同じ感じで表示されるのは良いですね。
       
      ・Font Awesomeのアイコン利用
      私は巷のWebサイトにあるTwtitterやFacebookのアイコンはああした画像ファイルをどこからか入手して img で指定しているのかと思ってたらFont Awesomeといったものがあるのですね。仕組みはGoogle Fontsと同じでネットワーク経由でアイコンのデータを取ってきて自身のWebサイトに表示するようです。これも面白そうだったのでやってみました。
      1. https://fontawesome.com/ にアクセス
      2. 画面上部の[ How to Use ]をクリック
      3. 画面中央に表示される(link rel=..)で始まるコードをHTMLファイルのheadタグの中にコピペ
      4. 画面上部の[ Icons ]をクリック。表示されるアイコン一覧から使いたいアイコンをクリックします。(色が薄く表示されているアイコンは有償のProプランに入っている人だけが使えます)
      5. 画面左下の(i class..)で始まるコードをHTMKファイル内のアイコンを表示させたい箇所にコピペ
      手順は以上です。既にFont Awesomeからアイコンを読み込んで表示しているのが確認できますが、素の状態だと結構シンプルというか地味です。
       
      なので書籍に従って、CSSファイルで以下の装飾を施します。
       
      だいぶそれっぽくなった気がします。各自で好きに装飾できるようにシンプルな状態で配布しているのですね。
       
      ・フレキシブルボックスレイアウトを使った可変レイアウト
      おそらくこの書籍のもっとも肝の部分の1つとなる、サイトを閲覧するデバイスの画面解像度に応じて表示レイアウトを可変させる、というのも基本部分だけやってみました。よりわかりやすいようにChromeのデベロッパーツールを使って確認していきます。
      1. 書籍に従って、index.htmlとstyle.cssを仕上げます。sectionやdivで区切られた要素がいくつあり、入れ子状態になっているものを意識します。
      2. iPhone6/7/8で見た場合、3つの要素(divで区切ったブロック)が縦1列に並んで表示されます。パソコンや他のデバイスを選択して表示しても同じです。
      3. 書籍に従って画面の横解像度が768pxを超えた場合は、3つの要素(divで区切ったブロック)を画面の横幅を等分割して横一列で表示する、という指示をCSSに書き加えます。
      4. 画面の横幅がちょうど768pxあるiPadで見ると、3つの要素(divで区切ったブロック)が画面の横幅を等分割して横一列で表示されています。
      5. 試しに3つの要素(divで区切ったブロック)をコピペで6つに増やしてみると... うまいこと等分割表示してくれているようです。
      まとめ
      Chromeのデベロッパーツールを使って色々なデバイスを呼び出しながら、かつ縦横を変えて表示の変化を確認しながら進めていくと飽きずに行けると思います。デバイスに応じた可変レイアウトもWordPressのテーマによってはほぼ自動で出来たりするようですが、実際の仕組みを理解しておくという意味でも良い書籍だと思いました。どなたかの参考になりましたら幸いです。
      2018/08/30 技術 / デザイン / 制作
    • 音ゲーの話

      こんにちは。 やっと過ごしやすい気候になってきて、秋って感じがしますね。 食欲の秋、スポーツの秋、芸術の秋、、、、 芸術の秋  →  音楽  →  音ゲー  

      ということで、無理やり「芸術の秋」に繋げて音ゲーの話をさせていただきます。

        基本的に私はあまりアプリのゲームはしないのですが、そんな私がハマった数少ないアプリゲームを紹介いたします! ある日なにか音ゲーたるものをしてみたく思い、App Storeで探していました。   (余談ですが、幼少期はプレステ2でパラッパラッパー系のゲームをよくプレイしていました)   で、探しているとユルい画像(私好み)が目に入ったので早速インストールしてみることに・・・。 https://itunes.apple.com/jp/app/%E3%81%86%E3%81%97%E3%82%8D-%E3%81%86%E3%81%97%E3%82%8D/id1091569546?mt=8 このゲームはニコニコ動画の ”踊ってみた”をしている最中にお母さんが入ってきてしまう  という、本当にあった動画を元ネタとして作られており、かなりシュールなゲームです。 元ネタ(諸説あり) →https://www.youtube.com/watch?v=ZKVmNjJE4jA   音楽もクセになるようなものばかりですし、キャラクターも変えてプレイできます(お母さんも踊ります)   ゆるーくできるゲームなので、気分転換にでも試してみてはいかがでしょうか?  
      2018/09/14 デバイス・端末 技術 / デザイン / 制作 日常 / プライベート