patterns for effectviely documenting frameworks
DESCRIPTION
9/29일 전자신문 세미나 자료TRANSCRIPT
![Page 1: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/1.jpg)
프레임워크 문서화 잘하기 (Patterns for Effectively Documenting Frameworks)
EVA 박선욱한국예탁결제원
서강대학교 SE 랩
![Page 2: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/2.jpg)
2
목차GoalWhat is FrameworksWhy Documenting Frameworks? What is The Good Framework Documentation?Introduce PatternsReference
![Page 3: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/3.jpg)
3
Offical Goal
객체지향 프레임워크의 효과적인 문서화 . (비전문가를 위한 )
![Page 4: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/4.jpg)
4
Personal Goal
프레임워크가 무엇인지 정확히 알기어떤 프레임워크든 빠르게 습득하기
![Page 5: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/5.jpg)
What is FrameworksDouglas C. Schmidt Says..
Frameworks define “semi-complete” applicationthat embody domain-specific object structures and functionality.
to produce custom application
+
![Page 6: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/6.jpg)
Class Library Component Architecture
App SpecificLogic
OO Design
EventLoop
DATABASE ADTs
MATH NETWORKING
GRAPHICS GUI
Singleton Strategy
Reactor Adapter
State Active Object
Invocations
Selections
Application Block
Design Pattern
Libraries is..
![Page 7: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/7.jpg)
DATABASE
Singleton
GRAPHICS
Adapter
EventLoop
Reactor
NETWORKING
Active Object
GUI
State
App SpecificLogic
MATH
ADTs
Callbacks
Invocations
Application FrameworkComponent Architecture
Control – Flow (IoC)
But Framework is ..
![Page 8: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/8.jpg)
8
Why Documenting Frameworks?
![Page 9: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/9.jpg)
Frameworks help us …
설계와 코드의 재사용을 통한생산성 향상빠른 개발호환성과 일관성의 향상
![Page 10: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/10.jpg)
10
Software reuse
상세한 소스코드부터 추상화된 아키텍처까지프레임워크는 중간에 위치하는 강력한 재사용 기술이다 .
Components ( 소스 ) + Patterns Technology (설계 )
![Page 11: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/11.jpg)
11
But …
No Pain! No Gain!For reuse
Good design and implementationAnd … ??
![Page 12: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/12.jpg)
12
Why Documenting Frameworks?
프레임워크는 확장성과 유연성을 가져야 한다 .이 부분은 본질적으로 어렵다 .
![Page 13: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/13.jpg)
13
Why Documenting Frameworks?
학습곡선은 좋은 문서로 단축시킬 수 있습니다 .
![Page 14: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/14.jpg)
14
Framework based development
Documenta-tion
Application
FrameworkDomain
designing andimplementing
evolving
documenting
understanding
understanding
applying
refining
framework developer
application developer
![Page 15: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/15.jpg)
15
What is The Good Framework Doc-umentation?
![Page 16: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/16.jpg)
16
What is The Good Technical Docu-mentation
Use
FindUnderstand
Task Orientation
Accuracy
Completeness
Organization
Retrievability
Visual Effectiveness
Clarity
Concreteness
Style
The book “Developing Quality Technical Infor-mation”
![Page 17: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/17.jpg)
17
Key Issues of Framework Documen-tation
내용측면Usage and Design 정보의 조화Contents 의 구조Contents 의 표현다양한 경로 제공
관리측면일관성과 중복다양한 표현방법Contents 의 통합
![Page 18: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/18.jpg)
18
Usage vs Design Information
좋은 제품은 내부 구조를 알지 못해도 사용할 수 있어야 한다 . 대부분의 프레임워크 문서들은 내부 설계와 아키텍처 설명에 집중되어 있다 .
But frameworks documentation must mix.
![Page 19: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/19.jpg)
19
What is The Good Framework Doc-umentation?
Reader’s point of view :task-oriented informationwell organizedunderstandableeasy to retrieve
Writer’s point of view : identifying the documentation needsselecting the contentschoosing the best representationorganizing the contents adequately
![Page 20: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/20.jpg)
20
Pattern LanguagesDocumenta-
tion Roadmap
Framework Overview
Cookbook and Recipes
Graded Ex-amples
Customizable Point
Design Inter-nals
Error Recov-ery Guide
Traversable Code
Reference Guide
where is start?first recipe
how-to’s
errors
uses
illustrate
how it works?
code
index
![Page 21: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/21.jpg)
21
This pattern language give us
가이드 라인이 되어준다 . 효과적이다 . 재사용을 지원한다 .
![Page 22: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/22.jpg)
22
Pattern Application: A Typical Se-quence
FRAMEWROK OVER-
VIEW
GRADED EXAMPLES
DOCUME-NATION
ROADMAP
COOKBOOK & RECIPES
CUSTMIZ-ABLE
POINTS
DESIGN IN-TERNAL
![Page 23: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/23.jpg)
23
Framework OverviewDocumenta-
tion Roadmap
Framework Overview
Cookbook and Recipes
Graded Ex-amples
Customizable Point
Design Inter-nals
Error Recov-ery Guide
Traversable Code
Reference Guide
where is start?first recipe
how-to’s
errors
uses
illustrate
how it works?
code
index
Pattern : Framework Overview
![Page 24: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/24.jpg)
24
What is the Framework Overview
![Page 25: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/25.jpg)
25
Problem
프레임워크의 첫인상을 어떻게 하면 빠르고 정확하게 알려줄 수 있을까 ? 즉 , 해당 프레임워크가 할 수 있는 것이 무엇인지 짧고도 정확하게 알려줄 수 있을까 ?
Pattern : Framework Overview
![Page 26: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/26.jpg)
26
Forces
다양한 독자들특히 , 프레임워크 선별자
완전성정보를 충분히 제공해야 한다 .그런데 , 문제는 독자 별로 ‘충분히’가 다르다 .
쉬운 이해 Clarity vs Completeness예제는 이해를 돕는데 탁월한 수단이다 .
![Page 27: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/27.jpg)
27
Different audiences
애플리케이션 개발자프레임워크 선별자프레임워크 개발자프레임워크 유지보수자다른 프레임워크 개발자
![Page 28: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/28.jpg)
28
Solution
프레임워크의 커버리지를 명시고정 ( 불가능한 영역 )유연 ( 가능한 영역 )
프레임워크의 도메인 용어를 구축프레임워크 선별자를 주 독자로 작성
Pattern : Framework Overview
![Page 29: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/29.jpg)
29
Example (JUnit)
Pattern : Framework Overview
![Page 30: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/30.jpg)
30Pattern : Framework Overview
Example (Spring)
![Page 31: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/31.jpg)
31
Pattern : Graded ExamplesDocumenta-
tion Roadmap
Framework Overview
Cookbook and Recipes
Graded Ex-amples
Customizable Point
Design Inter-nals
Error Recov-ery Guide
Traversable Code
Reference Guide
where is start?first recipe
how-to’s
errors
uses
illustrate
how it works?
code
index
Pattern : Graded Examples
![Page 32: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/32.jpg)
32
Problem
어떻게 독자가 자신의 애플리케이션에 해당 프레임워크 적용이 가능한지 알 수 있도록 도와 줄까 ?문인은 붓로 말하고 무인은 칼로 말한다 . 하지만 개발자들은 코드로 말한다 .
Pattern : Graded Examples
![Page 33: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/33.jpg)
33
Forces
Task 중심무엇을 할 수 있고 , 어떻게 하면 되나
다양한 독자들비용 (Cost) 대비 효율
TDD 를 한다면 , 별도의 예제를 따로 만들지 않아도 된다 .
![Page 34: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/34.jpg)
34
Solution
예제를 단계적으로 제공좋은 예제 집합
도메인 용어로 구성프레임워크 기능들의 표현다른 문서화를 완성시키는 역할
예제는추상화된 설계보다 이해하기 쉽다프레임워크의 유용성을 바로 알 수 있게 해준다프레임워크의 유용성 뿐만 아니라 제한성도 보여 준다 . 프레임워크의 설계가 아닌 사용법을 보여준다 .
Pattern : Graded Examples
![Page 35: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/35.jpg)
35
Example (JUnit)
Pattern : Graded Examples
![Page 36: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/36.jpg)
36
Example (Spring)
Pattern : Graded Examples
![Page 37: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/37.jpg)
37
Pattern : Documentation RoadmapDocumenta-
tion Roadmap
Framework Overview
Cookbook and Recipes
Graded Ex-amples
Customizable Point
Design Inter-nals
Error Recov-ery Guide
Traversable Code
Reference Guide
where is start?first recipe
how-to’s
errors
uses
illustrate
how it works?
code
index
![Page 38: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/38.jpg)
38
What is the Documentation Roadmap
![Page 39: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/39.jpg)
39
Problem
어떻게 하면 독자가 필요로 하는 정보를 쉽게 찾을 수 있도록 도와 줄 수 있을까 ?
Pattern : Documentation Roadmap
![Page 40: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/40.jpg)
40
Forces
다양한 독자들애플리케이션 개발자프레임워크 선별자프레임워크 개발자프레임워크 유지보수인다른 프레임워크 개발자
각기 다른 재사용찾는 방법의 난이도
Pattern : Documentation Roadmap
![Page 41: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/41.jpg)
41
Solution
Task 중심산발적 읽기도 지원
navigating top-down from a main entry point navigating bottom-up from a small piece of infor-mation.
전체적인 조정 가능성을 향상시켜라관련된 ( 독자 / 기능 / 사용순서 ) 주제끼리 묶어라 탭과 번호 , 단락 등을 이용하여 보기 좋게 하라
Pattern : Documentation Roadmap
![Page 42: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/42.jpg)
42
Example (JUnit)
Pattern : Documentation Roadmap
![Page 43: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/43.jpg)
43
Example (Spring)
Pattern : Documentation Roadmap
![Page 44: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/44.jpg)
44
Pattern : Cookbook & RecipesDocumenta-
tion Roadmap
Framework Overview
Cookbook and Recipes
Graded Ex-amples
Customizable Point
Design Inter-nals
Error Recov-ery Guide
Traversable Code
Reference Guide
where is start?first recipe
how-to’s
errors
uses
illustrate
how it works?
code
index
Pattern : Cookbook and Recipes
![Page 45: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/45.jpg)
45
What is Cookbok & Recipes
![Page 46: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/46.jpg)
46
Problem
어떻게 하면 독자가 빠르게 프레임워크를 사용 할 수 있게 해줄 수 있을까 ?
Pattern : Cookbook and Recipes
![Page 47: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/47.jpg)
47
Force
Task 중심 사용방법과 설계정보 사이의 균형다양한 독자들
초보자고수
완전성바로 적용할 수 있는 난이도비용대비 효과
![Page 48: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/48.jpg)
48
Solution
Cookbook레시피들을 나선형 구조로 나열 “Framework overview” is often the first recipe
레시피의 구성목적절차예제
Pattern : Cookbook and Recipes
![Page 49: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/49.jpg)
49
Example (JUnit)
Pattern : Cookbook and Recipes
![Page 50: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/50.jpg)
50Pattern : Cookbook and Recipes
Example
![Page 51: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/51.jpg)
51
Pattern : Customizable PointsDocumenta-
tion Roadmap
Framework Overview
Cookbook and Recipes
Graded Ex-amples
Customizable Point
Design Inter-nals
Error Recov-ery Guide
Traversable Code
Reference Guide
where is start?first recipe
how-to’s
errors
uses
illustrate
how it works?
code
index
![Page 52: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/52.jpg)
52
What is Customizable Point
Hot-spot 커스터마이제이션은 사전에 정의된 개선영역에 의해서 수행된다 .
Hook변경되어야 하는 영역과 방법 : 따라야 하는 제약사항과 Hook 의 영향Hot spot 은 하나 이상의 Hook 으로 구성
Pattern : Customizable Points
![Page 53: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/53.jpg)
53
Hot-spot Model
White Box Black Box
Pattern : Customizable Points
![Page 54: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/54.jpg)
54
Problem
독자에게 프레임워크에서 커스터마이징 가능한 부분을 알려주려면 어떻게 해야 할까 ? 그 부분들의 커스터마이징하는 방법을 알려주려면 어떻게 해야 할까 ?
Pattern : Customizable Points
![Page 55: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/55.jpg)
55
Force
Task 중심사용법과 설계정보 사이의 균형다양한 독자완전성문서에 대한 쉬운 이해
![Page 56: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/56.jpg)
56
Solution
별도로 커스터마이징 가능한 부분들의 목차를 제공
기능별부분이나 모듈별
잘 사용되지 않음사용법은 “ Cookbook & Recipes” 과 중복설계정보는 “ Design internals” 과 중복
Pattern : Customizable Points
![Page 57: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/57.jpg)
57
Example (Junit)
Pattern : Customizable Points
![Page 58: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/58.jpg)
58
Pattern : Design InternalsDocumenta-
tion Roadmap
Framework Overview
Cookbook and Recipes
Graded Ex-amples
Customizable Point
Design Inter-nals
Error Recov-ery Guide
Traversable Code
Reference Guide
where is start?first recipe
how-to’s
errors
uses
illustrate
how it works?
code
index
![Page 59: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/59.jpg)
59
Problem
진보된 커스터마징을 원하는 독자에게 어떻게 프레임워크의 설계와 구현에 대해서 알려줄 수 있을까 ?
Pattern : Design Internals
![Page 60: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/60.jpg)
60
Force
다른 목적들사용법과 설계정보 사이의 균형설계정보 복잡성의 최소화
Pattern : Design Internals
![Page 61: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/61.jpg)
61
Solution
정확하고 상세한 프레임워크의 내부 설계정보를 제공
especially hot-spots. can help them better understand and enable more advanced customizations
아키텍처와 설계원칙디자인 패턴을 이용
간단한 표현풍부한 정보 제공
Pattern : Design Internals
![Page 62: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/62.jpg)
62
Example (JUnit)
Pattern : Design Internals
![Page 63: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/63.jpg)
63
Review : Pattern LanguagesDocumenta-
tion Roadmap
Framework Overview
Cookbook and Recipes
Graded Ex-amples
Customizable Point
Design Inter-nals
Error Recov-ery Guide
Traversable Code
Reference Guide
where is start?first recipe
how-to’s
errors
uses
illustrate
how it works?
code
index
![Page 64: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/64.jpg)
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
![Page 65: Patterns for effectviely documenting frameworks](https://reader031.vdocuments.net/reader031/viewer/2022013100/5465e538af795982288b58f8/html5/thumbnails/65.jpg)
65
Q & A