└──
└── /Новая папка(2)/Новый текстовый документ.txt Новый текстовый документ(2).txt
- 어디에 이걸 적어놨지…
무거운 가정
작업 수행 속박 속에서 문서 작성해야 한다는 어려운 상황이 있었습니다. 파이프라인, 모니터링, 자동화, RnD, 지원 및 세부 시간 기록 간의 빈번한 전환은 문서화에 집중하는 것을 어렵게 만들었습니다.
기록하기
내 작업을 기록하고, 이미지를 추가하고, 링크와 태그로 텍스트를 보강하며, 주제가 동일한 한 곳에서 교차되지 않도록 했어야 했습니다. 모든 변경 사항을 추적할 수 있도록 해야 했습니다.
- Putty/Bash 로깅은 프로덕션에서 혼란스러운 작업 순서를 복구하는 데 도움이 되었습니다. 이러한 기회를 무시하지 마십시오.
게시
결과적으로 템플릿을 실행 가능한 문서로 변환하고 프로젝트 문서에 게시했습니다. 아름답게 경계를 넘어섰습니다.
목표는 확장된 서식으로 템플릿을 만들고 표준 게시 형식으로 전환하는 것이었습니다.
온라인 형식
결국 마크다운 + Git 형식을 사용하여 온라인 문서를 자동으로 생성했습니다. 브라우저 캐시에서 오프라인 모드를 사용할 수 있었습니다. 고객사 내부 네트워크에서도 유용하게 사용되었습니다. 고객도 이를 높이 평가했습니다.
마크다운은 GitLab, YouTrack, 일부 메신저 및 모든 LLM 모델에서 인식됩니다.
공유 템플릿
귀하의 작업이 재무와 관련이 없는 경우 템플릿을 공개해야 합니다. 오히려 협업할 수 있도록 허용해야 합니다.
제 템플릿을 공개하려는 열망은 "코드로서의 문서"를 만드는 데 도움이 되었습니다. DevOps 팀은 익명의 텍스트 파일과 검색 문제, “어디에 기록했는지” 문제를 해결했습니다. Word 버전 간의 차이점이나 깨진 이미지가 없습니다. 템플릿에서 바로 온라인 버전을 만들고 깔끔하고 엄격한 PDF를 생성할 수 있습니다.
문서화 오늘
- 마크다운 형식으로 작성 (Typora 또는 자동 저장 및 IDEA/PyCharm 커밋과 같은 유사한 편집기 사용)
- Gitlab에 저장 (모든 직원에게 역할 기반 액세스 권한을 제공하며 다중 사용자 편집을 지원합니다.)
- Docsify 컨테이너에서 온라인 버전으로 자동으로 생성 (코드 변경 사항은 매분마다 업데이트됩니다. DNS를 사용하여 웹 사이트를 브라우징합니다.)
- Vue.js와 동일한 방식으로 PDF로 쉽게 내보냅니다.
- Drawio 및 Mermaid 형식의 다이어그램을 사용합니다.
- SVG (드물게 PNG) 형식으로 다이어그램을 내보내고 원본 코드를 포함합니다.
부족한 점
대부분의 사용자에게는 단일 위치에서 문서를 저장하고 여러 사용자가 편집할 수 있는 기능을 갖춘 것이 중요하지 않습니다. 편집자-기여자는 한 명이고 일반 사용자는 많습니다. 그들은 필요한 문서를 빠르게 최신 버전으로 찾고 쉽게 공유해야 합니다. 다음 사항에 대해 몇 가지 질문이 있습니다.
- 문서 목록을 자동으로 생성합니다.
- 텍스트 내 링크를 관련 문서의 정확도에 따라 순위 지정합니다 (최근 수정 사항이 아닌 내용 기반).
- 문서 내에서 작은 수정을 직접 허용하여 소스 코드와 작업할 필요가 없습니다.
- 일부 문서 부분이 서로 연결되어 부분적으로 또는 완전히 재사용되므로 한 번에 여러 문서를 업데이트합니다.
- 문서화가 자동으로 생성되도록 합니다. 왜냐하면 그것은 매우 빠르게 구식이 되기 때문입니다.
- 관련 직원 댓글을 공개 채널이나 커뮤니티에서 상기시키고, 문서의 권위 (문서 작성자와 관련된 사람의 말)를 우선시합니다.
세 번째 항목은 Discourse와 같은 일부 플랫폼에서 이미 구현되었습니다. AI가 구조화된 문서화를 돕는 데 도움이 될 것입니다.