Technical Writing (11) 썸네일형 리스트형 Write the Docs Newsletter – September 2022 Newsletter를 읽고 나름 감상평(?)과 실무진으로서 경험담을 적어보고자 한다. Collecting helpful user feedback 유저 피드백받는 거 정말 소중하고 도움되는 거 맞지만.. ㅜㅜ 막상 피드백이 오는 경우가 잘 없더라..ㅎ 개인적인 경험으로는 신입 개발자들 온보딩 절차로 문서 읽고 피드백 내게 하는 프로세스가 제일 좋은 것 같다. 새로 입사했을 때가 제일 fresh eye로 열정 가득하게(?) 집중해서 보는 시기이기도 하고 해서- 그때 받은 피드백들이 문서 고치고 quality improve 하는데 제일 도움된 듯. Some have had good results with prefilled feedback options as a middle ground between open-.. Docs as Code Docs as Code란 code를 작성할 때와 같은 툴로 문서를 써야 한다는 일종의 철학이다. 2가지 관점에서 생각해볼 수 있다. 1. Git, Markdown, Code Review같이 코드를 작성하고 배포할 때 쓰는 동일한 툴을 docs를 쓸 때도 이용하는 것 2. 새로운 기능이 배포될 때 문서까지 같이 배포되는 것을 하나의 프로세스로 자리잡게 하는 것 (그러려면 배포 일정에 맞춰 스케줄 관리를 해야 하는데 PM이 하는 곳도 있고, Technical Writer가 문서 PM 역할을 하기도 함) -> 이 과정에서 자연스럽게 개발팀도 ownership을 가지고 문서에 기여하는 것이 중요함 Documentation as Code (Docs as Code) refers to a philosophy that.. The technical writing process technical writing이 반드시 'writing'에만 국한되지는 않는다. technical writing에서 필요한 작업은 visual design, editing 그리고 project management 등을 포함함. TW는 이 중 일부를 하게 될 수도 있고 아니면 혼자 다하게 될 수도 있음 why? 심심찮게 테크니컬 라이터가 1명인 곳도 많으므로. What you can expect (maybe) 1. Identify the needed deliverables deliverables이란 최종 산출물, final products를 말함 e.g. books, online help, web pages, tutorials, videos 등등 2. Develop an outline or a plan .. Visual Communication 사례 조사 직업병인지 아무래도 Technical Writer로 일하면서 다른 회사 Docs 사이트들은 어떻게 돼있는지 유심히 보는 습관이 생겼다. 회사에서 Technical Writing 101 발표 준비를 하다- Chapter 8에서 Visual Communication 얘기가 나오길래 (근데 책은 내용이 아무래도 올드하니까) 발표 준비도 할겸 다른 Docs 사이트들 visual communication trend를 찾아봤다. 전체 스크린샷 vs. 부분 스크린샷 pros and cons 전체 스크린샷 장점: 메뉴를 포함한 전체 화면을 볼 수 있음 단점: (부분 스크린샷과 반대의 이유로) 너무 많은 정보가 있으면 화면에서 어디에 해당 메뉴가 있는지 파악하기 어려움 화면 UI가 (자주) 바뀌면 문서도 지속적으로 업데.. Structured authoring with XML e.g. mindMup, SimpleMind Structured authoring 하려면 결국 툴의 도움을 받으면 좋다 구조가 명확하게 보여서 편집하기 좋음 마인드맵 보여주면서 TOC 설명, 공유하면 이해하기 쉬움 Structured authoring이란? a publishing workflow that defines and enforces consistent organization of information 정보의 일관된 구조를 정의하고 강화하는 publishing 작업 흐름이다. 간단한 구조화된 document 예시로 recipe를 들 수 있음 보통 전형적인 recipe는 여러가지 구성 요소를 필요로 함 a name a list of ingredients instructions 요리책에 대한 스타일 .. Final preparation - production editing production editing이란? the process of finalizing the appearance of content 콘텐츠의 모양새를 마무리하는 과정 time to verify the presentation of that content before distribution to users 사용자에게 배포되기 전에 최종 점검 단계 production editing’s purpose? to ensure that content follows the formatting guidelines in template-based workflows verifying the correct styles from the template are applied correctly ensure that each elem.. The importance of being edited Editing process가 있으면 도움되는 점 Improve the organization, tone, and consistency of your content Correct spelling and grammatical errors 일관성있는 콘텐츠를 확보하려면 프로젝트 초기에 style guideline을 만들어야 함 ⭐️ Style guide가 있으면 좋은 점 모두의 수고를 덜어줌 어떤 rule을 지켜야할지 미리 알면 text가 much more consistent require less rework later on editor는 문서가 적절한 audience level에 맞춰 필요한 정보를 제공하는지 보장함 Preventive measures (예방책) The editing process를 프로.. Writing task-oriented information 항상 audience를 염두에 두고 있어야 함 다음 question을 고려해야 함 Does each step represent an action the user takes? Are the results of an action clearly explained? Would a graphic help explain an action more clearly? Elements of a procedure task-oriented information steps requiring action by the user information about the results of those actions to clarify what the user does graphics tables notes Introducing the .. Getting information Techical writer’s primary task란? to give people the information they need to use technology 해당 기술을 사용하기 위해 필요한 정보를 사용자에게 제공하는 것 그러기 위해 ferreting out that information (해당 정보를 찾아내는 것)이 가장 어려운 일이 될 수도 있음 Technical specifications and other development content A technical or functional specification (known as a spec)이란? 담당 product 개발자에 의해 쓰여진 문서 이 문서는 해당 제품의 목적과 이 제품이 어떻게 동작하는지를 설명함 Typical informati.. Very necessary evils - doc plans and outlines doc plan과 outline을 짜기 위해선 제품에 관한 대략적인 정보가 필요함 e.g. product prototype, technical specification (“spec”) that lists the product’s features doc plan을 공유하면 좋은 점? 문서 이해관계자들이 스케줄에 맞춰 문서를 만들어내기 위해 각자 무엇을, 언제까지 해야하는지 이해할 수 있음 What’s a doc plan? doc plan은 콘텐츠 개발 프로젝트의 모든 구성요소를 다 서술함 doc plan은 다음 정보를 포함해야 함 Product description a brief summary of what the product does 1~2 문장으로 이 제품이 어떤 역할을 하는지 간단하게 요약 Audi.. 이전 1 2 다음
