Patterns for effectviely documenting frameworks

Patterns for effectviely documenting frameworks

• 1. 프레임워크 문서화 잘하기 (Patterns for Effectively Documenting Frameworks)EVA 박선욱한국예탁결제원서강대학교 SE랩
• 2. 목차GoalWhat is FrameworksWhy Documenting Frameworks? What is The Good Framework Documentation?Introduce PatternsReference
• 3. Offical Goal객체지향 프레임워크의 효과적인 문서화. (비전문가를 위한)
• 4. Personal Goal프레임워크가 무엇인지 정확히 알기어떤 프레임워크든 빠르게 습득하기
• 5. What is FrameworksDouglas C. Schmidt Says..Frameworks define “semi-complete” applicationthat embody domain-specific object structures and functionality.+to produce custom application
• 6. Libraries is..Application BlockDATABASEADTsMATHNETWORKINGApp SpecificLogicOO DesignInvocationsGRAPHICSGUIEventLoopSingletonStrategySelectionsReactorAdapterStateActive ObjectDesign PatternClass Library Component Architecture
• 7. But Framework is ..Control – Flow (IoC)Active ObjectStateNETWORKINGGUIMATHReactorEventLoopApp SpecificLogicInvocationsCallbacksADTsSingletonAdapterDATABASEGRAPHICSApplication FrameworkComponent Architecture
• 8. Why Documenting Frameworks?
• 9. Frameworks help us …설계와 코드의 재사용을 통한생산성 향상빠른 개발호환성과 일관성의 향상
• 10. Software reuse상세한 소스코드부터 추상화된 아키텍처까지프레임워크는 중간에 위치하는 강력한 재사용 기술이다.Components (소스) + Patterns Technology (설계)
• 11. But …No Pain! No Gain!For reuseGood design and implementationAnd … ??
• 12. Why Documenting Frameworks?프레임워크는 확장성과 유연성을 가져야 한다.이 부분은 본질적으로 어렵다.
• 13. Why Documenting Frameworks?학습곡선은 좋은 문서로 단축시킬 수 있습니다.
• 14. Framework based developmentApplicationrefiningapplyingdesigning andimplementingFrameworkDomainunderstandingapplication developerevolvingunderstandingDocumentationframework developerdocumenting
• 15. What is The Good Framework Documentation?
• 16. What is The Good Technical DocumentationThe book “Developing Quality Technical Information”
• 17. Key Issues of Framework Documentation내용측면Usage and Design 정보의 조화Contents의 구조Contents의 표현다양한 경로 제공관리측면일관성과 중복다양한 표현방법Contents의 통합
• 18. Usage vs Design Information좋은 제품은 내부 구조를 알지 못해도 사용할 수 있어야 한다. 대부분의 프레임워크 문서들은 내부 설계와 아키텍처 설명에 집중되어 있다. But frameworks documentation must mix.
• 19. What is The Good Framework Documentation?Reader’s point of view :task-oriented informationwell organizedunderstandableeasy to retrieveWriter’s point of view : identifying the documentation needsselecting the contentschoosing the best representationorganizing the contents adequately
• 20. Pattern LanguagesDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide
• 21. This pattern language give us 가이드 라인이 되어준다. 효과적이다. 재사용을 지원한다.
• 22. Pattern Application: A Typical Sequence
• 23. Framework OverviewDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference GuidePattern : Framework Overview
• 24. What is the Framework Overview
• 25. Problem프레임워크의 첫인상을 어떻게 하면 빠르고 정확하게 알려줄 수 있을까? 즉, 해당 프레임워크가 할 수 있는 것이 무엇인지 짧고도 정확하게 알려줄 수 있을까?Pattern : Framework Overview
• 26. Forces다양한 독자들특히, 프레임워크 선별자완전성정보를 충분히 제공해야 한다.그런데, 문제는 독자 별로 ‘충분히’가 다르다.쉬운 이해ClarityvsCompleteness예제는 이해를 돕는데 탁월한 수단이다.
• 27. Different audiences애플리케이션 개발자프레임워크 선별자프레임워크 개발자프레임워크 유지보수자다른 프레임워크 개발자
• 28. Solution프레임워크의 커버리지를 명시고정(불가능한 영역)유연(가능한 영역)프레임워크의 도메인 용어를 구축프레임워크 선별자를 주 독자로 작성Pattern : Framework Overview
• 29. Example (JUnit)Pattern : Framework Overview
• 30. Pattern : Framework OverviewExample (Spring)
• 31. Pattern : Graded ExamplesDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference GuidePattern : Graded Examples
• 32. Problem어떻게 독자가 자신의 애플리케이션에 해당 프레임워크 적용이가능한지 알 수 있도록 도와 줄까?문인은 붓로말하고 무인은 칼로 말한다. 하지만개발자들은 코드로 말한다.Pattern : Graded Examples
• 33. ForcesTask 중심무엇을 할 수 있고, 어떻게 하면 되나다양한 독자들비용(Cost)대비 효율TDD를 한다면, 별도의 예제를 따로 만들지 않아도 된다.
• 34. Solution예제를 단계적으로 제공좋은 예제 집합도메인 용어로 구성프레임워크 기능들의 표현다른 문서화를 완성시키는 역할예제는추상화된 설계보다 이해하기 쉽다프레임워크의 유용성을 바로 알 수 있게 해준다프레임워크의 유용성 뿐만 아니라 제한성도 보여 준다. 프레임워크의 설계가 아닌 사용법을 보여준다.Pattern : Graded Examples
• 35. Example (JUnit)Pattern : Graded Examples
• 36. Example (Spring)Pattern : Graded Examples
• 37. Pattern : Documentation RoadmapDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide
• 38. What is the Documentation Roadmap
• 39. Problem어떻게 하면 독자가 필요로 하는 정보를 쉽게 찾을 수 있도록 도와 줄 수 있을까?Pattern : Documentation Roadmap
• 40. Forces다양한 독자들애플리케이션 개발자프레임워크 선별자프레임워크 개발자프레임워크 유지보수인다른 프레임워크 개발자각기 다른 재사용찾는 방법의 난이도Pattern : Documentation Roadmap
• 41. SolutionTask 중심산발적 읽기도 지원navigating top-down from a main entry point navigating bottom-up from a small piece of information.전체적인 조정 가능성을 향상시켜라관련된(독자/기능/사용순서) 주제끼리 묶어라 탭과 번호, 단락 등을 이용하여 보기 좋게 하라Pattern : Documentation Roadmap
• 42. Example (JUnit)Pattern : Documentation Roadmap
• 43. Example (Spring)Pattern : Documentation Roadmap
• 44. Pattern : Cookbook & RecipesDocumentation Roadmap Framework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference GuidePattern : Cookbook and Recipes
• 45. What is Cookbok & Recipes
• 46. Problem어떻게 하면 독자가 빠르게 프레임워크를 사용 할 수 있게 해줄 수 있을까?Pattern : Cookbook and Recipes
• 47. ForceTask 중심사용방법과 설계정보 사이의 균형다양한 독자들초보자고수완전성바로 적용할 수 있는 난이도비용대비 효과
• 48. SolutionCookbook레시피들을나선형 구조로 나열“Framework overview” is often the first recipe레시피의 구성목적절차예제Pattern : Cookbook and Recipes
• 49. Example (JUnit)Pattern : Cookbook and Recipes
• 50. ExamplePattern : Cookbook and Recipes
• 51. Pattern : Customizable PointsDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide
• 52. What is Customizable PointHot-spot 커스터마이제이션은사전에 정의된 개선영역에 의해서 수행된다.Hook변경되어야 하는 영역과 방법 : 따라야 하는 제약사항과 Hook의 영향Hot spot은 하나 이상의 Hook으로 구성Pattern : Customizable Points
• 53. Hot-spot ModelWhite Box Black BoxPattern : Customizable Points
• 54. Problem독자에게 프레임워크에서 커스터마이징 가능한 부분을 알려주려면 어떻게 해야 할까? 그 부분들의커스터마이징하는 방법을 알려주려면 어떻게 해야 할까?Pattern : Customizable Points
• 55. ForceTask 중심사용법과 설계정보 사이의 균형다양한 독자완전성문서에 대한 쉬운 이해
• 56. Solution별도로 커스터마이징 가능한 부분들의 목차를 제공기능별부분이나 모듈별잘 사용되지 않음사용법은 “Cookbook & Recipes”과 중복설계정보는 “Design internals”과 중복Pattern : Customizable Points
• 57. Example (Junit)Pattern : Customizable Points
• 58. Pattern : Design InternalsDocumentation Roadmap Framework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide
• 59. Problem진보된 커스터마징을 원하는 독자에게 어떻게 프레임워크의 설계와 구현에 대해서 알려줄 수 있을까?Pattern : Design Internals
• 60. Force다른 목적들사용법과 설계정보 사이의 균형설계정보 복잡성의 최소화Pattern : Design Internals
• 61. Solution정확하고 상세한 프레임워크의 내부 설계정보를 제공especially hot-spots. can help them better understand and enable more advanced customizations 아키텍처와 설계원칙디자인 패턴을 이용간단한 표현풍부한 정보 제공Pattern : Design Internals
• 62. Example (JUnit)Pattern : Design Internals
• 63. Review : Pattern LanguagesDocumentation RoadmapFramework Overviewfirst recipewhere is start?how-to’sCookbook and RecipesError Recovery GuideerrorsusesGraded ExamplescodeillustrateCustomizable PointTraversable Codehow it works?Design InternalsindexReference Guide
• 64. Reference“Patterns for Effectively Documenting Frameworks” –Ademar Aguiar and Gabriel David“질서 있는 아키텍처 패턴이야기” – 김용현(마이크로소프트웨어)“Framework Engineering” – 손영수(www.arload.net)www.junit.orgwww.springsource.orgwww.google.comwww.evacast.net
• 65. Q & A