Upgrade to Pro — share decks privately, control downloads, hide ads and more …

目的に沿ったDocumentation as Codeをいかにして実現していくか / PHPerKaigi 2021

目的に沿ったDocumentation as Codeをいかにして実現していくか / PHPerKaigi 2021

https://fortee.jp/phperkaigi-2021/proposal/42ce8b07-6972-42bb-a2ac-96af7249cfa4

あるシステムを理解して開発を開始するとき、必要なのはInfrastructure as Codeを含むソースコードだけでは大抵の場合は不十分です。では挙動がわかるようなテストコードがあれば十分かというとそうでもありません。
いわゆる「オンボーディングの効果的な運用」「開発開始までのオーバヘッドの削減(PHPerKaigi2020で発表)」は継続的な生産性向上のためには考えなければならない要素です。
そして、上記を補完するためにしばしばドキュメントが書かれます。

私はドキュメント運用のアプローチとして「コードによる生成を含んだドキュメント運用」に興味を持っています。
私はこれを「Documentation as Code」と呼んでいます。そして、そのような概念はすでに世の中にあり、時として「Documentation as Code」と呼ばれているようです。
例えばPHPDocなどはソースコード自体の構造とアノテーションをトレースしてドキュメントの自動生成を実現しています。
OpenAPIのように構造化されたデータとして情報を記述することでドキュメントと同時にAPIクライアントやの自動生成が実現できている例もあります。 これらはコードによってドキュメントが管理されており、継続的なドキュメンテーションも実現可能です。
さて、ドキュメントと言っても「何を解決するためのドキュメント」なのかを考える必要があると思います。
本発表では、上記のような「Documentation as Code」を実現するツールを独自にモデル化してそれぞれの特性について考えます。
そして、どのような「Documentation as Code」が「開発開始までのオーバヘッドの削減」に繋がるのか、私が実際に取り組んだ(また取り組んでいる)事例を交えて考えていきたいと思います。

Ken’ichiro Oyama

March 27, 2021
Tweet

More Decks by Ken’ichiro Oyama

Other Decks in Technology

Transcript

  1. 

  2. ։ൃ։࢝·ͰͷΦʔόʔϔου w ৽ن։ൃͷ৔߹ɺ࣮ࡍʹ։ൃΛ։࢝ ͢Δ·Ͱʹࠨਤʹ͋ΔΑ͏ͳෳ਺ͷ ϨΠϠʔʹ͍ͭͯݕ౼Λ͢Δ w ๨ΕΒΕ͕͕ͪͩɺ్த͔Β։ൃʹ +0*/͢Δ৔߹΋ɺ৽ن։ൃ࣌ͱಉ͡ ਺ͷϨΠϠʔͷཧղ͕ඞཁʹͳΔ w

    ҧ͏ͷ͸ʮ͢Ͱʹ͋Δ΋ͷΛཧղ ͢Δඞཁ͕͋Δʯͱ͍͏͜ͱ͚ͩ  IUUQTTQFBLFSEFDLDPNLMPXQIQFSLBJHJʹमਖ਼ΛՃ͑ͨ΋ͷ ͲͷΑ͏ͳαʔϏε͔ ͲͷΑ͏ͳΞʔΩςΫνϟ͔ ͲͷΑ͏ʹσʔλΛอ࣋͢Δ͔ ʢʹͲͷΑ͏ͳςʔϒϧઃܭ͔ʣ ͲͷΑ͏ͳ։ൃ؀ڥ͔ ʢຊ൪؀ڥɾ։ൃ؀ڥʣ ͲͷΑ͏ͳίʔυ͔ ։ൃ αʔϏεཧղϨΠϠʔ ΞʔΩςΫνϟཧղϨΠϠʔ σʔλετΞཧղϨΠϠʔ ։ൃ؀ڥཧղϨΠϠʔ ίʔυཧղϨΠϠʔ
  3. γεςϜͱυΩϡϝϯτͷဃ཭͕͋Δͱ w γεςϜͱͷဃ཭͕͋ΔυΩϡϝϯτͰγεςϜΛཧղ͢ΔͱɺؒҧͬͨཧղͰ։ൃʹ ೖͬͯ͠·͏ w ࣮͸ؔ࿈͕૿͍͑ͯͯؾܰʹ੾Γ཭ͤͳ͘ͳ͍ͬͯͨΠϯελϯε w ࣮͸ߟྀ͠ͳ͍ͱ͍͚ͳ͍͜ͱ͕มΘ͍ܾͬͯͨࡁػೳ w ࣮͸૿͍͑ͯͨόον

    w ։ൃऀ͕ͦͷဃ཭ʹؾͮ͘ͷ͕஗͚Ε͹஗͍΄Ͳ։ൃʹ͓͚ΔϚΠφε͕େ͖͘ͳΔ w γεςϜཧղͷ΍Γͳ͓͠🔥 w ίʔυͷॻ͖௚͠🔥🔥 w ؒҧͬͨཧղͷ··ϦϦʔεɺޙʹো֐🔥🔥🔥🔥🔥🔥 
  4. %PDVNFOUBUJPOBT$PEF %PDTBT$PEF SFGFSTUPBQIJMPTPQIZUIBUZPV TIPVMECFXSJUJOHEPDVNFOUBUJPOXJUIUIFTBNFUPPMTBTDPEF *TTVF5SBDLFST 7FSTJPO$POUSPM (JU  1MBJO5FYU.BSLVQ .BSLEPXO

    SF4USVDUVSFE5FYU "TDJJEPD  $PEF3FWJFXT "VUPNBUFE5FTUT 5IJTNFBOTGPMMPXJOHUIFTBNFXPSLqPXTBTEFWFMPQNFOUUFBNT BOE CFJOHJOUFHSBUFEJOUIFQSPEVDUUFBN*UFOBCMFTBDVMUVSFXIFSFXSJUFST BOEEFWFMPQFSTCPUIGFFMPXOFSTIJQPGEPDVNFOUBUJPO BOEXPSL UPHFUIFSUPNBLFJUBTHPPEBTQPTTJCMF IUUQTXXXXSJUFUIFEPDTPSHHVJEFEPDTBTDPEFɹΑΓൈਮɹ 
  5. ϞσϧԽ ొ৔͢Δཁૉͱͯͭ͠  ։ൃऀ  γεςϜʜ։ൃऀ͕։ൃ΍ઃఆΛ͢Δର৅ɻίʔυɺΞϓϦέʔγϣϯɺσʔλ ϕʔεɺΠϯϑϥͳͲɻγεςϜࣗମ͸ߏ଄Խ͞Ε͍ͯΔʢ΋ͷΛର৅ͱ͢Δʣ  υΩϡϝϯτ 

    ߏ଄Խσʔλʜʮ:".-ʯ΍ʮϓϩάϥϜίʔυͷ"45ʯͳͲɻ ٯʹɺʮγεςϜʹର͢Δ։ൃऀͷཧղɾΠϝʔδʯ͸ෆఆܗͰ։ൃऀͦΕͧΕ ͕಄ͷதͰ͍࣋ͬͯΔ͚ͩͳͷͰߏ଄Խ͸͞Ε͍ͯΔͱ͸ݴ͑ͳ͍  ιϑτ΢ΣΞʜԿ͔͠ΒͷॲཧΛߦ͏ϓϩάϥϜɻߏ଄ԽσʔλΛೖग़ྗͱ͠ ΍͍͢ͱ͍͏ಛ௃Λ࣋ͭ 
  6. 

  7. UCMT w $*ϑϨϯυϦͳσʔλϕʔευΩϡϝϯτੜ੒πʔϧ w IUUQTHJUIVCDPNL-P8UCMT w 1PTUHSF42- .Z42-ͳͲͷ3%#.4͚ͩͰͳ͘ɺ #JH2VFSZ΍"NB[PO%ZOBNP%# $MPVE4QBOOFS

    ͱ͍ͬͨσʔλιʔεʹ΋ରԠ w υΩϡϝϯτΛॆ࣮ͤ͞Δػೳͱͯ͠ϝλσʔλΛ Ξϊςʔγϣϯ͢Δ͜ͱ͕Մೳ w ςʔϒϧɺΧϥϜͳͲͷίϝϯτ෇༩͚ͩͰͳ͘ λάɺϦϨʔγϣϯͳͲ 
  8. 

  9. OEJBH --- name: 3-Tier Architecture docPath: ../output Views: - name:

    overview layers: ["consul", "vip_group"] - name: http-lb layers: ["vip_group"] labels: ["http"] nodes: - name: lb-* components: - nginx?icon=lb-l7 clusters: - 'consul:dc1' - 'vip_group:lb' - name: app-* components: - nginx?icon=proxy - Rails?icon=cube4 clusters: - 'consul:dc1' - name: db-* components: - PostgreSQL?icon=db clusters: - 'consul:dc1' networks: - labels: - http route: 
  10. OEJBH w IUUQTHJUIVCDPNL-P8OEJBH w ʮΤψσΟΞάʯʮΤψμΠΞάʯͲͪΒͰ΋ ndiag doc -c ndiag.yml w

    ੜ੒͞ΕΔυΩϡϝϯτ͸(JU)VCʹίϛοτͯ͠8FC্͔ΒӾཡ͞ΕΔ͜ͱ૝ఆ w ओʹΠϯϑϥͷϋΠϨϕϧΞʔΩςΫνϟͷυΩϡϝϯτΛੜ੒͢Δ໨తͰ։ൃ w :".-͔Βʮߏ੒ਤΛੜ੒͢ΔʯͰ΋ʮυΩϡϝϯτΛੜ੒͢ΔʯͰ΋ͳ͘ ʮෳ਺ͷ੾ΓޱͰʯʮߏ੒ਤΛؚΉʯʮυΩϡϝϯτͷ਽ܗΛ࡞Δʯ ͱ͍͏ಛ௃Λ࣋ͭ 
  11. υΩϡϝϯτͷΧόϨοδ w UCMT΋OEJBH΋υΩϡϝϯτ͸ʮ݀ຒΊʯͷঢ়ଶʹ·Ͱ͍͚͍࣋ͬͯͯΔ w υΩϡϝϯτͷΧόϨοδܭଌ͕ՄೳˠͦΕͧΕΧόϨοδܭଌػೳΛ࣋ͭ  ndiag coverage Elements Coverage

    All Elements 21% (53/252) Views 66.7% (2/3) Nodes 100% (36/36) Components 15.4% (18/117) Relations 0% (0/67) Layers 100% (7/7) Labels 28.6% (6/21)
  12. ·ͱΊ w ։ൃ։࢝·ͰͷΦʔόʔϔουΛ࡟ݮ͢ΔυΩϡϝϯτΛӡ༻͍ͯͨ͘͠Ίʹ͸ ʮ%PDVNFOUBUJPOBT$PEFʯΛجຊͱ͠ͳ͕Β΋ɺʮܧଓతʹʯӡ༻Ͱ͖Δ࢓૊Έɺ ʮγεςϜͷཧղΛॿ͚Δʯ࢓૊Έ͕ඞཁͩͱ͍͏͜ͱΛओுͨ͠ w ܧଓతυΩϡϝϯςʔγϣϯͷͨΊʹ͸γεςϜͱυΩϡϝϯτͷဃ཭Λ൑ఆ͠খ͞ ͘͢Δ࢓૊Έ͕ඞཁͰ͋Δ͜ͱΛ঺հͨ͠ɻ w γεςϜͷཧղΛॿ͚ΔυΩϡϝϯτͷͭͷํ๏ͱͯ͠ʮγεςϜશମΛද͢ͷͰ͸

    ͳ͘ɺγεςϜͷཧղʹҙຯͷ͋ΔάϧʔϐϯάΛͯͦ͠ΕͧΕυΩϡϝϯτԽ͢ ΔɻͦΕͧΕͷཧղΛॏͶΔ͜ͱͰγεςϜશମͷཧղʹͭͳ͛Δʯͱ͍͏ํ๏Λ঺ հͨ͠ɻ w ʮܧଓతυΩϡϝϯςʔγϣϯʯͱʮγεςϜͷཧղΛॿ͚ΔυΩϡϝϯςʔγϣ ϯʯΛཱ྆ͯ͠ॳΊͯ։ൃ։࢝·ͰͷΦʔόʔϔουΛ࡟ݮͰ͖Δ