Upgrade docs #21
Upgrade docs #21
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
| </DoDont.Do> | ||
| </DoDont> | ||
|
|
||
| ### ✅ 기능-가치-예시 구조로 작성하세요 |
There was a problem hiding this comment.
아래 두 가지 내용이 서로 겹쳐보이죠..?
- 기능 중심 설명을 피하고, 독자가 얻을 가치를 먼저 전달하세요
- 기능-가치-예시 구조로 작성하세요
작성할 당시에는 1번이 (세부 문장을 작성하기 전에) "문서에 정보를 배치하는 방법" 이라고 생각했고, 2번이 "문장을 작성할 때 지켜야 하는 논리 순서"라고 생각해서 서로 별개라고 생각했는데요.
다시 읽어보니까 1번도 문장 작성할 때 적용할 수 있는 원칙이라는 생각이 드네요 ㅠ
There was a problem hiding this comment.
그럼 요건 내용에서 제외하고, 1번에 예시를 함께 제시하면 더욱 도움이 된다~ 정도로만 덧붙여볼게요!
|
|
||
| 예제 코드를 함께 제공하면 독자가 직접 실행해 보며 동작을 확인할 수 있어요. 이렇게 하면 문서가 단순한 설명을 넘어 실제 사용 경험을 전달하는 학습 자료가 되며, 독자의 이해도와 몰입도가 함께 높아집니다. | ||
|
|
||
| 참조 링크를 활용하면 사용자가 스스로 관련 정보를 찾아볼 수 있습니다. 이렇게 하면 문서의 길이를 늘이지 않고도 맥락을 전달할 수 있고, 독자가 주도적으로 학습할 수 있는 여지를 마련해 줍니다. |
There was a problem hiding this comment.
| 참조 링크를 활용하면 사용자가 스스로 관련 정보를 찾아볼 수 있습니다. 이렇게 하면 문서의 길이를 늘이지 않고도 맥락을 전달할 수 있고, 독자가 주도적으로 학습할 수 있는 여지를 마련해 줍니다. | |
| 참조 링크를 활용하면 사용자가 스스로 관련 정보를 찾아볼 수 있어요. 자세한 설명을 링크로 연결하면 문서의 길이를 늘이지 않고도 맥락을 전달할 수 있고, 독자가 주도적으로 학습할 수 있습니다. |
이렇게 쓰면 좀 더 자연스러울 것 같은데 어떠세요?!
|
|
||
| ### 1. 독자가 정보를 더 쉽게 이해할 수 있습니다 | ||
|
|
||
| 다이어그램, 순서도, 표 같은 시각 자료를 활용하면 글로 설명하기 어려운 개념이나 절차를 독자에게 한눈에 보여줄 수 있어요. 그래서 정보의 흐름을 더 직관적으로 파악할 수 있어 이해하기 쉬워요. |
There was a problem hiding this comment.
| 다이어그램, 순서도, 표 같은 시각 자료를 활용하면 글로 설명하기 어려운 개념이나 절차를 독자에게 한눈에 보여줄 수 있어요. 그래서 정보의 흐름을 더 직관적으로 파악할 수 있어 이해하기 쉬워요. | |
| 다이어그램, 순서도, 표 같은 시각 자료를 사용하면 복잡한 정보를 한눈에 보여줄 수 있어요. 특히 글로 설명하기 어려운 개념이나 절차를 훨씬 쉽게 이해할 수 있게 도와줘요. |
- 두 문장의 흐름(두 문장이 같은 이야기를 하고 있어서 동어 반복 같은 느낌)도 각각의 문장도 좀 어색해서 위와 같이 고쳐봤어요. 일단, 가치를 첫 번째 문장에 확실하게 알려주고, 두 번째 문장에서 확장했어요.
- '독자에게'라는 말은 이미 문서의 대상이 독자이므로 생략해도 의미에 문제 없을 거 같아요. 없애면 문장을 더 간결하게 만들 수 있을 것 같은데 어때요?
- '파악할 수 있어 이해하기 쉬워요'는 비슷한 뜻의 동사가 연속되는 거 같아 고쳤어요.
|
|
||
| ### 2. 문서의 신뢰도를 높입니다 | ||
|
|
||
| 공식 문서나 자세한 설명으로 연결되는 참조 링크를 활용하면 정보가 검증된 근거를 바탕으로 작성되었다는 인상을 줄 수 있습니다. 독자는 “이 문서는 근거가 있는 정보다”라는 신뢰가 생기는 거예요. |
There was a problem hiding this comment.
이 문장은 무척 인공적으로 느껴지네요 ㅋㅋ "인상을 준다"는 표현은 문서 작성자의 의도에 초점을 두지만, 사실 독자가 느끼는 건 '인상'이 아니라 '신뢰'여야 하는 거라서 잘 맞지 않는 논거 같아요.
|
|
||
| ### 2. 문서의 신뢰도를 높입니다 | ||
|
|
||
| 공식 문서나 자세한 설명으로 연결되는 참조 링크를 활용하면 정보가 검증된 근거를 바탕으로 작성되었다는 인상을 줄 수 있습니다. 독자는 “이 문서는 근거가 있는 정보다”라는 신뢰가 생기는 거예요. |
There was a problem hiding this comment.
| 공식 문서나 자세한 설명으로 연결되는 참조 링크를 활용하면 정보가 검증된 근거를 바탕으로 작성되었다는 인상을 줄 수 있습니다. 독자는 “이 문서는 근거가 있는 정보다”라는 신뢰가 생기는 거예요. | |
| 공식 문서나 신뢰할 수 있는 자료로 연결되는 참조 링크를 제공하면, 독자가 정보의 출처를 직접 확인할 수 있어서 문서의 신뢰도가 높아져요. |
근데 이렇게 고치더라도 논거가 좀 부족해 보이네용.. 이게 정말 중요한 파트인지 한 번 다시 고민해봐도 좋을 듯 해요
|
|
||
| # 보조 자료 활용하기 | ||
|
|
||
| 좋은 문서는 독자에게 맥락을 풍부하게 제공합니다. 하지만 모든 정보를 한 문서에 담으려 하면 주제가 분산되고, 정보량이 지나치게 많아질 수 있어요. 이때 예시 코드, 사진, 그래프 같은 보조 자료를 활용해야 합니다. 그렇게 하면 독자에게 정보를 더 쉽고 직관적으로 전달할 수 있습니다. |
There was a problem hiding this comment.
| 좋은 문서는 독자에게 맥락을 풍부하게 제공합니다. 하지만 모든 정보를 한 문서에 담으려 하면 주제가 분산되고, 정보량이 지나치게 많아질 수 있어요. 이때 예시 코드, 사진, 그래프 같은 보조 자료를 활용해야 합니다. 그렇게 하면 독자에게 정보를 더 쉽고 직관적으로 전달할 수 있습니다. | |
| 좋은 문서는 독자에게 맥락을 풍부하게 제공합니다. 하지만 모든 정보를 한 문서에 담으려 하면 주제가 분산되고, 정보량이 지나치게 많아질 수 있어요. 이때 예시 코드, 흐름도, 가독성을 높이는 컴포넌트 같은 보조 자료를 활용해야 합니다. 그렇게 하면 독자에게 정보를 더 쉽고 직관적으로 전달할 수 있습니다. |
사진, 그래프는 기술 문서에서 잘 사용하지 않아 어색해요. 또 마지막에 컴포넌트 관련 내용도 있는데 처음에 소개가 잘 되지 않은 거 같아 추가하면 좋을 듯 해요.
|
|
||
| ### 3. 중요한 정보를 효과적으로 전달할 수 있습니다 | ||
|
|
||
| 본문의 모든 내용이 동일한 형태로 나열되어 있으면, 독자는 어떤 부분이 중요한지 빠르게 구분하기 어려워요. 이럴 때 콜아웃, 참조 링크, 하이라이트 블록 같은 요소를 활용하면 독자가 주의해야 할 부분과 참고할 부분을 자연스럽게 인지할 수 있습니다. |
There was a problem hiding this comment.
| 본문의 모든 내용이 동일한 형태로 나열되어 있으면, 독자는 어떤 부분이 중요한지 빠르게 구분하기 어려워요. 이럴 때 콜아웃, 참조 링크, 하이라이트 블록 같은 요소를 활용하면 독자가 주의해야 할 부분과 참고할 부분을 자연스럽게 인지할 수 있습니다. | |
| 본문의 모든 내용이 텍스트로만 나열되어 있으면 가독성이 떨어지거나 어떤 부분이 중요한지 한눈에 구분하기 어려워요. 이럴 때 콜아웃, 참조 링크, 하이라이트 블록 같은 요소를 쓰면 주의해야 할 내용이나 참고할 정보를 자연스럽게 구분할 수 있어요. |
There was a problem hiding this comment.
동일한 형태 라는 말이 모호해서 더 구체적으로 적어봤어요. 나머지는 단순 문장 다듬기입니다!
|
|
||
| ### ✅ 예시 코드를 작성하세요 | ||
|
|
||
| 예제 코드는 핵심 기능을 잘 드러낼 수 있고 간단해야 해요. 그리고 독자가 직접 실행해보며 학습할 수 있도록 예제 코드를 실행하는 데 문제가 없는지 확인해야 합니다. |
There was a problem hiding this comment.
어떨 때 예제 코드가 필요한지도 써주면 더 좋을 거 같아요.
|
|
||
| ### ✅ 시각 자료를 활용하세요 | ||
|
|
||
| 시각 자료는 단순히 보기에 좋은 자료보다 전달하고자 하는 정보를 명확하게 보여주는 자료를 선택해야 해요. 독자가 정보를 잘 이해하도록 돕는 목적으로 활용하기 때문이에요. |
There was a problem hiding this comment.
이것도 어떤 경우에 시각 자료를 활용하면 좋은지, 그리고 시각 자료라고 했을 때 예시 이미지 / 흐름도 등 다양한 요소가 있는데 각각의 용도가 다를 수 있어 구체적으로 적어야 할 것 같습니다.
|
|
||
| ### ✅ 참조할 수 있는 링크를 제공하세요 | ||
|
|
||
| 문서에서 직접 설명하기 어려운 배경지식이나 세부 정보가 있을 때는 관련 문서나 공식 자료로 연결되는 참조 링크를 추가하세요. |
There was a problem hiding this comment.
어렵다를 좀 더 구체적으로 풀어보면 어때요? 예를 들어 특정 개념에 대해 설명하는 게 문서의 목적과 맞지 않은 경우 < 등으로 설명을 하는 게 더 적절할 거 같아요.
| ### ✅ 괄호 사용을 줄이세요 | ||
|
|
||
| 괄호를 사용하면 독자가 헷갈릴 수 있는 정보를 부연 설명할 수 있어요. 문서를 작성할 때 대표적으로 다음과 같은 상황에서 괄호를 사용해요. |
There was a problem hiding this comment.
괄호 사용을 줄이라는 게 헤딩인데, 첫 문장은 괄호를 사용하라는 내용이라 흐름이 어색해요.
There was a problem hiding this comment.
맨 아래 내용이 먼저 나오고, 그치만 이럴 때는 괄호를 쓰는 게 좋다 라는 흐름이 자연스러울 듯 합니다.
| ::: details 정답 확인 | ||
|
|
||
| 시스템은 서버가 재시작되어도 자동으로 로그를 유지합니다 |
| </DoDont.Dont> | ||
| <DoDont.Do> | ||
|
|
||
| 자동 백업 기능은 데이터베이스를 주기적으로 저장하여 장애 발생 시에도 복구할 수 있도록 합니다. |
There was a problem hiding this comment.
| 자동 백업 기능은 데이터베이스를 주기적으로 저장하여 장애 발생 시에도 복구할 수 있도록 합니다. | |
| 자동 백업 기능은 데이터베이스를 주기적으로 저장해서 장애 발생 시에도 쉽게 복구할 수 있도록 하는 기능이에요. |
예시지만 문장이 딱딱하고 어색하게 느껴져서 좀 더 개선할 수 있을 것 같아요.
2 participants
수정한 내용
이 변경이 필요한 이유
확인이 필요한 내용
체크리스트