TL:DR? 좋아요...여기:
기술 작가를 고용하거나 아웃소싱하는 것보다 적절한 IT 문서를 작성하고 시간이 지남에 따라 해당 문서를 유지하기 위해 배울 수 있는 기술 작가가 업무에 사용하는 기본 표준/협약/관행이 있습니까?
직원들의 내부 IT 사용과 외부 사용을 위해 다양한 문서를 작성하면서 문서에 관해서는 직원들 모두 자신만의 스타일이 있다는 것이 분명해졌습니다.
IT는 품질 문서와 통제 문서를 바탕으로 SOP, WI용 다양한 템플릿과 IT 품질 문서에 사용되는 다양한 양식을 활용했습니다. 이러한 문서는 IT 내의 일상적인 작업에 반드시 유용하지는 않지만 IT HR 문제, 규정 준수 등과 관련된 직원과 회사에 도움이 되며 일반적으로 잘 작성되고 잘 정의되어 있으며 최소한 품질 부서의 템플릿을 따릅니다. 및 문서 표준(예: 버전 관리, ECN 등)
그러나 실제 IT 문서 작성에는 여전히 진정한 규칙/표준이 부족합니다. 일부는 ScreenSteps와 같은 타사 도구를 사용하고 다른 일부는 단순히 Word를 사용하여 다음과 같은 간단한 개요를 만듭니다.
- 열려 있는
app- '글로벌 열핵전쟁 시작'을 클릭하세요.
- ...
- 이익
내부 IT 문서는 실제로 더 나쁩니다., 직원이나 컨설턴트가 당시 자신의 기억을 되살리기에 충분하다고 느꼈거나 선택한 편집기(vi, word, excel, powerpoint, napkin, 내부 wiki)를 기반으로 한 내용을 기반으로 합니다. 문제는 직원이 퇴사하거나 휴가 중이어서 기본 정보까지 파악하기 위해 쟁탈전을 벌일 때 발생한다. 때로는 파일 날짜만이 데이터가 여전히 관련성이 있는지 여부를 나타내는 지표가 됩니다.
간단한 개요, 실제 스크린샷, 심지어 HD 비디오의 전체 내용은 모두 훌륭하지만 우리 직원에는 실제 IT 기술 작가가 없으며 이 분야에서 우리가 부족하다고 생각하지 않을 수 없습니다.
승인된 템플릿과 함께 문서에 대한 자체 표준을 만들 수 있습니까? 예, 그런데 왜 바퀴를 다시 발명합니까? 그러한 표준과 규칙이 Technical Writer의 "길드" 내에 이미 존재한다면 문서가 명확하고 간결하며 전문적이도록 그러한 규칙을 따르는 것이 더 나을 것입니다.
말을 듣지 않으려면"구글잇", 몇 가지 형식 지정 방법을 보여주는 사이트를 살펴보았는데 이 SF Q는 다음과 같습니다.IT 문서화 플랫폼글쓰기를 처리할 플랫폼과 소프트웨어를 찾는 데 도움이 되지만 업계 내에 실제로 표준이 있는지는 논의하지 않습니다.
그렇다면 기술 작가를 고용하거나 아웃소싱하는 것보다 적절한 IT 문서를 작성하고 시간이 지남에 따라 해당 문서를 유지하기 위해 배울 수 있는 기술 작가가 업무에 사용하는 기본 표준/관습/관행이 있습니까?
답변1
글쓰기는 훈련이다.
나는 그것을 많이 해봤다., 그리고 저는 훈련받지 않은 사람이 문서를 작성하지 않고도 얻을 수 있는 만큼의 기본 사항을 업무의 가장 중요한 부분으로 알고 있습니다. 시간은 내가 작성한 문서가 실제로 읽혀질지, Eternal TL;DR의 선반에 무엇이 들어갈지 보여주었습니다. 사실 이것은 무엇이든 작성하는 데 있어 가장 중요한 규칙입니다.
청중을 알아라.
내부 IT 문서의 대상은 우리 자신입니다. 그리고 시스템 관리자? 문서, 특히 내부 문서를 찾을 때 우리는 다음을 찾습니다.
- 위치 확인 가능
- 짧은
- 요점까지
- 내가 가는 곳으로 나를 데려다준다
시스템 배경에 대한 5문단 설명은 아래 체크리스트를 위해 무시됩니다. 왜냐하면 우리는 서두르고 작업을 완료해야 하기 때문입니다. 그리고 거기에 경고가 있으면특정 단계를 순서대로 수행하면 모든 백업이 지워집니다.건너뛴 텍스트 블록에 관심을 끄는 형식이 있거나 해당 비트도 체크리스트에 포함되어야 할 수도 있습니다.
프로세스 문서
이러한 유형의 문서는 작업을 수행하는 방법을 설명하는 것입니다. 대부분 따라야 할 일련의 단계를 적는 것이기 때문에 훈련받지 않은 사람이 제작하는 것이 가장 쉽습니다. 내 경험에 따르면 좋은 프로세스 문서화에는 다음과 같은 특징이 있습니다.
- 체크리스트가 포함되어 있습니다.
- 체크리스트는 체크리스트가 실행되는 시기와 이유에 대한 간략한 요약과 같은 페이지에 있습니다.
- 체크리스트 아래 또는 링크된 페이지에는 체크리스트 이면의 이론과 발생할 수 있는 변형을 설명하는 긴 문서가 있습니다.
따라야 할 체크리스트가 있고 필요한 경우 페이지에 이미 있는 첫 번째 수준의 문제 해결 단계(또는 한 번의 클릭)가 있기를 원합니다.
이는 Microsoft KB 문서(요약, 수정, 세부 정보, 영향을 받는 시스템)를 본 적이 있다면 익숙한 형식입니다. 그럴만한 이유가 있습니다.
문제 해결 가이드
이는 의사결정 트리를 문서에 인코딩해야 하기 때문에 프로세스 문서화보다 까다롭습니다. 간단한 체크리스트로는 충분하지 않을 수 있지만 다른 체크리스트에 대한 링크를 사용하는 분기 체크리스트는 상당히 가능합니다. 이러한 종류의 문서에는 프로세스 문서와 동일한 규칙이 적용됩니다.
- 간결하게 작성하고 독자를 세부적으로 익사시키지 마십시오.
- 결정 지점이 무엇인지, 후속 조치를 위해 어디로 가야 하는지 명확히 하십시오.
- 건축 문서에 대한 심층적인 기술 배경 자료를 저장하세요.
문제 해결 가이드는 자신만의 모험을 선택하는 큰 스토리일 수도 있고, 시스템에서 발생한 모든 문제와 해결 방법을 나열한 큰 글머리 기호 목록일 수도 있습니다.
아키텍처 문서
생산하기 가장 어려운 단일 유형입니다. 방금 들어왔던 이 복잡한 것에 대해 머리를 감싸고 싶어하는 새로운 사람들만 참조할 수 있는 참조 자료로 설계되었기 때문입니다.
건축 문서는 Why 문서입니다. 이것이 저 시스템이 아닌 이 시스템이 사용되고 있는 이유, 이 시스템이 다른 시스템과 어떻게 연결되어 있는지, 그리고 그 연결이 예전처럼 작동하도록 만든 이유입니다. 프로덕션 구성이 어떻게 생겼는지 알게 되자마자 작성하고 변경 사항이 있으면 업데이트해야 하는 문서입니다.
형식적으로는 이 문제에 대해서는 전문가에게 맡겨야 합니다.
좋은 문서화는 단지 템플릿과 형식 그 이상입니다. 통일된 모양이 좋고 가독성을 향상시키며, 다른 것들도 필요합니다.
정기 업데이트
이미 가지고 있는 문서를 검토하여 문서가 여전히 양호한지 확인하는 습관을 들이십시오. 버전 1.17의 체크리스트는 버전 1.26에 적합하지 않을 수 있습니다. 업데이트할 시간입니다. 암기 체크리스트는 가장 작은 UI 변경으로도 전체 작업이 중단될 수 있으므로 가장 많은 업데이트가 필요합니다.
10분을 투자하다일주일문서를 검토하고 정리가 필요한 항목을 식별하는 것은 놀라운 일을 할 수 있습니다.
아키텍처 문서는 시스템을 아는 사람이 정기적으로 검토해야 합니다. 앞서 언급했듯이 이 문서는 거의 사용되지 않지만 실제로 필요할 때 매우 유용합니다. 3년 전에 Windows로 마이그레이션할 때 캠퍼스 인쇄 서비스 클러스터가 NetWare와 함께 연결되는 방법을 설명하는 문서는 원하지 않습니다.
검색 가능
이것은 매우 큰 부분을 좌우하기 때문에 올바르게 하기가 가장 어렵습니다.어디당신은 문서를 저장하고 있습니다.
ServerFault를 통해 질문을 받는 사람에게 우리는 무엇을 말합니까?
이미 무엇을 시도하셨나요?
곧 이어서
Google의 최고 히트작이 문제를 해결해 드립니다. 아마도 당신은 그것을 시도해야 할 것입니다.
우리는 문서를 검색할 뿐 책장으로 가지 않습니다. 문서 저장소는 Google만큼 검색 가능해야 합니다. 그렇지 않으면 대신 Google로 이동하겠습니다.
중앙 냅킨 저장소는 적어도 온라인 색인이 없는 경우(그리고 앞으로도 없을 경우) 문서화에 적합하지 않은 장소입니다. 간단한 위키는 대부분 최소한 기본적인 텍스트 검색을 포함하므로 더 좋습니다. 더 나은 시스템은 전체 텍스트 외에도 태그를 검색하여 대상 영역에 더 집중적으로 검색할 수 있도록 하는 시스템입니다.
태그를 지원하는 문서 저장소로 작업하는 경우,태그 표준화. 이유를 알아보려면 ServerFault 태그 목록을 한번 살펴보세요. 사용자는 8개의 순열을 외울 필요가 없습니다.VM웨어단지 그들이 찾고 있는 물건을 찾기 위해서입니다. 이를 위해서는 가끔 태그를 다시 지정하는 노력이 필요합니다.