Patterns for effectviely documenting frameworks

15,808 views

Published on

9/29일 전자신문 세미나 자료

Published in: Technology
1 Comment
22 Likes
Statistics
Notes
  • 좋은 문서 공유 감사드립니다..

    그런데.. 한국인 대상 PPT로 보이는데...
    한글로 충분히 표현 가능한 부분까지 왜 영어로 쓰여져 있는 부분이 읽기 불편하네요...
    대체 할 수 없는 부분만 영어로 해주셨으면 하는 작은 바램을 .. 적어 봅니다 ;
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total views
15,808
On SlideShare
0
From Embeds
0
Number of Embeds
1,311
Actions
Shares
0
Downloads
148
Comments
1
Likes
22
Embeds 0
No embeds

No notes for slide

Patterns for effectviely documenting frameworks

  1. 1. 프레임워크 문서화 잘하기 (Patterns for Effectively Documenting Frameworks)<br />EVA 박선욱<br />한국예탁결제원<br />서강대학교 SE랩<br />
  2. 2. 목차<br />Goal<br />What is Frameworks<br />Why Documenting Frameworks? <br />What is The Good Framework Documentation?<br />Introduce Patterns<br />Reference<br />
  3. 3. Offical Goal<br />객체지향 프레임워크의 효과적인 문서화. (비전문가를 위한)<br />
  4. 4. Personal Goal<br />프레임워크가 무엇인지 정확히 알기<br />어떤 프레임워크든 빠르게 습득하기<br />
  5. 5. What is Frameworks<br />Douglas C. Schmidt Says..<br />Frameworks define “semi-complete” application<br />that embody domain-specific object structures and functionality.<br />+<br />to produce custom application<br />
  6. 6. Libraries is..<br />Application Block<br />DATABASE<br />ADTs<br />MATH<br />NETWORKING<br />App Specific<br />Logic<br />OO Design<br />Invocations<br />GRAPHICS<br />GUI<br />Event<br />Loop<br />Singleton<br />Strategy<br />Selections<br />Reactor<br />Adapter<br />State<br />Active Object<br />Design Pattern<br />Class Library <br />Component Architecture<br />
  7. 7. But Framework is ..<br />Control – Flow (IoC)<br />Active Object<br />State<br />NETWORKING<br />GUI<br />MATH<br />Reactor<br />Event<br />Loop<br />App Specific<br />Logic<br />Invocations<br />Callbacks<br />ADTs<br />Singleton<br />Adapter<br />DATABASE<br />GRAPHICS<br />Application Framework<br />Component Architecture<br />
  8. 8. Why Documenting Frameworks?<br />
  9. 9. Frameworks help us …<br />설계와 코드의 재사용을 통한<br />생산성 향상<br />빠른 개발<br />호환성과 일관성의 향상<br />
  10. 10. Software reuse<br />상세한 소스코드부터 추상화된 아키텍처까지<br />프레임워크는 중간에 위치하는 강력한 재사용 기술이다.<br />Components (소스) + Patterns Technology (설계)<br />
  11. 11. But …<br />No Pain! No Gain!<br />For reuse<br />Good design and implementation<br />And … ??<br />
  12. 12. Why Documenting Frameworks?<br />프레임워크는 확장성과 유연성을 가져야 한다.<br />이 부분은 본질적으로 어렵다.<br />
  13. 13. Why Documenting Frameworks?<br />학습곡선은 좋은 문서로 단축시킬 수 있습니다. <br />
  14. 14. Framework based development<br />Application<br />refining<br />applying<br />designing andimplementing<br />Framework<br />Domain<br />understanding<br />application developer<br />evolving<br />understanding<br />Documentation<br />framework developer<br />documenting<br />
  15. 15. What is The Good Framework Documentation?<br />
  16. 16. What is The Good Technical Documentation<br />The book “Developing Quality Technical Information”<br />
  17. 17. Key Issues of Framework Documentation<br />내용측면<br />Usage and Design 정보의 조화<br />Contents의 구조<br />Contents의 표현<br />다양한 경로 제공<br />관리측면<br />일관성과 중복<br />다양한 표현방법<br />Contents의 통합<br />
  18. 18. Usage vs Design Information<br />좋은 제품은 내부 구조를 알지 못해도 사용할 수 있어야 한다. <br />대부분의 프레임워크 문서들은 내부 설계와 아키텍처 설명에 집중되어 있다. <br />But frameworks documentation must mix.<br />
  19. 19. What is The Good Framework Documentation?<br />Reader’s point of view :<br />task-oriented information<br />well organized<br />understandable<br />easy to retrieve<br />Writer’s point of view : <br />identifying the documentation needs<br />selecting the contents<br />choosing the best representation<br />organizing the contents adequately<br />
  20. 20. Pattern Languages<br />Documentation Roadmap<br />Framework Overview<br />first recipe<br />where is start?<br />how-to’s<br />Cookbook and Recipes<br />Error Recovery Guide<br />errors<br />uses<br />Graded Examples<br />code<br />illustrate<br />Customizable Point<br />Traversable Code<br />how it works?<br />Design Internals<br />index<br />Reference Guide<br />
  21. 21. This pattern language give us <br />가이드 라인이 되어준다. <br />효과적이다. <br />재사용을 지원한다.<br />
  22. 22. Pattern Application: A Typical Sequence<br />
  23. 23. Framework Overview<br />Documentation Roadmap<br />Framework Overview<br />first recipe<br />where is start?<br />how-to’s<br />Cookbook and Recipes<br />Error Recovery Guide<br />errors<br />uses<br />Graded Examples<br />code<br />illustrate<br />Customizable Point<br />Traversable Code<br />how it works?<br />Design Internals<br />index<br />Reference Guide<br />Pattern : Framework Overview<br />
  24. 24. What is the Framework Overview<br />
  25. 25. Problem<br />프레임워크의 첫인상을 어떻게 하면 빠르고 정확하게 알려줄 수 있을까? 즉, 해당 프레임워크가 할 수 있는 것이 무엇인지 짧고도 정확하게 알려줄 수 있을까?<br />Pattern : Framework Overview<br />
  26. 26. Forces<br />다양한 독자들<br />특히, 프레임워크 선별자<br />완전성<br />정보를 충분히 제공해야 한다.<br />그런데, 문제는 독자 별로 ‘충분히’가 다르다.<br />쉬운 이해<br />ClarityvsCompleteness<br />예제는 이해를 돕는데 탁월한 수단이다.<br />
  27. 27. Different audiences<br />애플리케이션 개발자<br />프레임워크 선별자<br />프레임워크 개발자<br />프레임워크 유지보수자<br />다른 프레임워크 개발자<br />
  28. 28. Solution<br />프레임워크의 커버리지를 명시<br />고정(불가능한 영역)<br />유연(가능한 영역)<br />프레임워크의 도메인 용어를 구축<br />프레임워크 선별자를 주 독자로 작성<br />Pattern : Framework Overview<br />
  29. 29. Example (JUnit)<br />Pattern : Framework Overview<br />
  30. 30. Pattern : Framework Overview<br />Example (Spring)<br />
  31. 31. Pattern : Graded Examples<br />Documentation Roadmap<br />Framework Overview<br />first recipe<br />where is start?<br />how-to’s<br />Cookbook and Recipes<br />Error Recovery Guide<br />errors<br />uses<br />Graded Examples<br />code<br />illustrate<br />Customizable Point<br />Traversable Code<br />how it works?<br />Design Internals<br />index<br />Reference Guide<br />Pattern : Graded Examples<br />
  32. 32. Problem<br />어떻게 독자가 자신의 애플리케이션에 해당 프레임워크 적용이가능한지 알 수 있도록 도와 줄까?<br />문인은 붓로말하고 무인은 칼로 말한다. 하지만개발자들은 코드로 말한다.<br />Pattern : Graded Examples<br />
  33. 33. Forces<br />Task 중심<br />무엇을 할 수 있고, 어떻게 하면 되나<br />다양한 독자들<br />비용(Cost)대비 효율<br />TDD를 한다면, 별도의 예제를 따로 만들지 않아도 된다.<br />
  34. 34. Solution<br />예제를 단계적으로 제공<br />좋은 예제 집합<br />도메인 용어로 구성<br />프레임워크 기능들의 표현<br />다른 문서화를 완성시키는 역할<br />예제는<br />추상화된 설계보다 이해하기 쉽다<br />프레임워크의 유용성을 바로 알 수 있게 해준다<br />프레임워크의 유용성 뿐만 아니라 제한성도 보여 준다. <br />프레임워크의 설계가 아닌 사용법을 보여준다.<br />Pattern : Graded Examples<br />
  35. 35. Example (JUnit)<br />Pattern : Graded Examples<br />
  36. 36. Example (Spring)<br />Pattern : Graded Examples<br />
  37. 37. Pattern : Documentation Roadmap<br />Documentation Roadmap<br />Framework Overview<br />first recipe<br />where is start?<br />how-to’s<br />Cookbook and Recipes<br />Error Recovery Guide<br />errors<br />uses<br />Graded Examples<br />code<br />illustrate<br />Customizable Point<br />Traversable Code<br />how it works?<br />Design Internals<br />index<br />Reference Guide<br />
  38. 38. What is the Documentation Roadmap<br />
  39. 39. Problem<br />어떻게 하면 독자가 필요로 하는 정보를 쉽게 찾을 수 있도록 도와 줄 수 있을까?<br />Pattern : Documentation Roadmap<br />
  40. 40. Forces<br />다양한 독자들<br />애플리케이션 개발자<br />프레임워크 선별자<br />프레임워크 개발자<br />프레임워크 유지보수인<br />다른 프레임워크 개발자<br />각기 다른 재사용<br />찾는 방법의 난이도<br />Pattern : Documentation Roadmap<br />
  41. 41. Solution<br />Task 중심<br />산발적 읽기도 지원<br />navigating top-down from a main entry point <br />navigating bottom-up from a small piece of information.<br />전체적인 조정 가능성을 향상시켜라<br />관련된(독자/기능/사용순서) 주제끼리 묶어라 <br />탭과 번호, 단락 등을 이용하여 보기 좋게 하라<br />Pattern : Documentation Roadmap<br />
  42. 42. Example (JUnit)<br />Pattern : Documentation Roadmap<br />
  43. 43. Example (Spring)<br />Pattern : Documentation Roadmap<br />
  44. 44. Pattern : Cookbook & Recipes<br />Documentation Roadmap<br /> Framework Overview<br />first recipe<br />where is start?<br />how-to’s<br />Cookbook and Recipes<br />Error Recovery Guide<br />errors<br />uses<br />Graded Examples<br />code<br />illustrate<br />Customizable Point<br />Traversable Code<br />how it works?<br />Design Internals<br />index<br />Reference Guide<br />Pattern : Cookbook and Recipes<br />
  45. 45. What is Cookbok & Recipes<br />
  46. 46. Problem<br />어떻게 하면 독자가 빠르게 프레임워크를 사용 할 수 있게 해줄 수 있을까?<br />Pattern : Cookbook and Recipes<br />
  47. 47. Force<br />Task 중심<br />사용방법과 설계정보 사이의 균형<br />다양한 독자들<br />초보자<br />고수<br />완전성<br />바로 적용할 수 있는 난이도<br />비용대비 효과<br />
  48. 48. Solution<br />Cookbook<br />레시피들을나선형 구조로 나열<br />“Framework overview” is often the first recipe<br />레시피의 구성<br />목적<br />절차<br />예제<br />Pattern : Cookbook and Recipes<br />
  49. 49. Example (JUnit)<br />Pattern : Cookbook and Recipes<br />
  50. 50. Example<br />Pattern : Cookbook and Recipes<br />
  51. 51. Pattern : Customizable Points<br />Documentation Roadmap<br />Framework Overview<br />first recipe<br />where is start?<br />how-to’s<br />Cookbook and Recipes<br />Error Recovery Guide<br />errors<br />uses<br />Graded Examples<br />code<br />illustrate<br />Customizable Point<br />Traversable Code<br />how it works?<br />Design Internals<br />index<br />Reference Guide<br />
  52. 52. What is Customizable Point<br />Hot-spot <br />커스터마이제이션은사전에 정의된 개선영역에 의해서 수행된다.<br />Hook<br />변경되어야 하는 영역과 방법 : 따라야 하는 제약사항과 Hook의 영향<br />Hot spot은 하나 이상의 Hook으로 구성<br />Pattern : Customizable Points<br />
  53. 53. Hot-spot Model<br />White Box <br />Black Box<br />Pattern : Customizable Points<br />
  54. 54. Problem<br />독자에게 프레임워크에서 커스터마이징 가능한 부분을 알려주려면 어떻게 해야 할까? <br />그 부분들의커스터마이징하는 방법을 알려주려면 어떻게 해야 할까?<br />Pattern : Customizable Points<br />
  55. 55. Force<br />Task 중심<br />사용법과 설계정보 사이의 균형<br />다양한 독자<br />완전성<br />문서에 대한 쉬운 이해<br />
  56. 56. Solution<br />별도로 커스터마이징 가능한 부분들의 목차를 제공<br />기능별<br />부분이나 모듈별<br />잘 사용되지 않음<br />사용법은 “Cookbook & Recipes”과 중복<br />설계정보는 “Design internals”과 중복<br />Pattern : Customizable Points<br />
  57. 57. Example (Junit)<br />Pattern : Customizable Points<br />
  58. 58. Pattern : Design Internals<br />Documentation Roadmap<br /> Framework Overview<br />first recipe<br />where is start?<br />how-to’s<br />Cookbook and Recipes<br />Error Recovery Guide<br />errors<br />uses<br />Graded Examples<br />code<br />illustrate<br />Customizable Point<br />Traversable Code<br />how it works?<br />Design Internals<br />index<br />Reference Guide<br />
  59. 59. Problem<br />진보된 커스터마징을 원하는 독자에게 어떻게 프레임워크의 설계와 구현에 대해서 알려줄 수 있을까?<br />Pattern : Design Internals<br />
  60. 60. Force<br />다른 목적들<br />사용법과 설계정보 사이의 균형<br />설계정보 복잡성의 최소화<br />Pattern : Design Internals<br />
  61. 61. Solution<br />정확하고 상세한 프레임워크의 내부 설계정보를 제공<br />especially hot-spots. <br />can help them better understand and enable more advanced customizations <br />아키텍처와 설계원칙<br />디자인 패턴을 이용<br />간단한 표현<br />풍부한 정보 제공<br />Pattern : Design Internals<br />
  62. 62. Example (JUnit)<br />Pattern : Design Internals<br />
  63. 63. Review : Pattern Languages<br />Documentation Roadmap<br />Framework Overview<br />first recipe<br />where is start?<br />how-to’s<br />Cookbook and Recipes<br />Error Recovery Guide<br />errors<br />uses<br />Graded Examples<br />code<br />illustrate<br />Customizable Point<br />Traversable Code<br />how it works?<br />Design Internals<br />index<br />Reference Guide<br />
  64. 64. Reference<br />“Patterns for Effectively Documenting Frameworks” –Ademar Aguiar and Gabriel David<br />“질서 있는 아키텍처 패턴이야기” – 김용현(마이크로소프트웨어)<br />“Framework Engineering” – 손영수(www.arload.net)<br />www.junit.org<br />www.springsource.org<br />www.google.com<br />www.evacast.net<br />
  65. 65. Q & A<br />

×