문서화에대해서 약간의 질문과 의견을 듣습니다
글쓴이: whitelazy / 작성시간: 목, 2003/11/20 - 11:10오후
간단한 동아리 세미나 자료 준비하다가 문득 떠올라서 질문드립니다
여기 오시는분들은 현업에 종사하시는분들도 있고
학생분들도 많죠
분야가 분야다보니 문서작업하실일이 많을꺼 같은데
문서화 작업할때 어떤것들이 포함되어야 한다고 생각하십니까??
간단한 또는 복잡한 학술적 목적으로 무언가를 준비할때랑
현업에서 업무 목적으로 문서화하실때랑요...
이번이 매학기 1번씩해서 네번째지만.. 아직도 무엇을 준비하여야
서로 도움이 될지 모르겠네요...
제가 로봇관련동아리라 이번 전시회때 만들은 로봇에 관해 준비합니다
프로그램이나 저런 로봇이나 임베디드 시스템등을 만들었을시 문서화 할때 필요한것에 대해 조언을 얻고 싶습니다
p.s. 여기저기 보다보면 문서화 관련 프로그램들이 많습니다. 이런 프로그램들이 실질적으로 어떤부분에서 도움이 됩니까?? 아직 써보진 못했지만 조금씩 필요를 느낍니다 버전관리랑 문서화쪽에...;; 워낙 난잡하게 짜는지라 유틸리티의 도움이 필요할듯하군요 ㅠ_ㅠ
Forums:
저는
저는 하나의 대원칙이 있는데요
소스의 문서화이건 프로젝트 전체의 문서이건간에
일단 그 대상에 대해서 전혀 모르는 사람이 봤을때도 이해가 될만큼
최대한 치밀하게입니다.
그러니까 이 문서를 읽을 사람이 제반 지식이 전혀 없다고 가정하고
작성합니다. 그래서 세세한 부분까지 신경을 씁니다.
왜냐면... 시간이 흐르고 나면 제 자신이 전혀 제반 지식이 없어지거든요...
그러니까 이 문서를 읽기 위해 필요한 제반 사항이나 기본 지식들도
같이 기록합니다. 좀 시간이 걸리고 양도 많지만 나중을 위해서지요..
음... 주제랑 좀 거리가 먼것 같기도 합니다. 죄송합니다. oops
[quote="gurugio"]소스의 문서화이건 프로젝트 전체의 문서이건
gurugio님의 글에 전적으로 동의합니다. 문서를 만들다 보면 자신의 입장에서 작성할 때가 많습니다. 즉... 배경지식은 모두 빼 버리고... 현재 만들어 낸 부분이 어떤 특징을 가지고 있고... 어떤 기술을 썼다에만 집중하는 경우가 있어 보통 사람이 보았을 때... 잘 이해하지 못하는 부분이 있습니다.
MS, 한컴, 노턴 등 이들 회사의 제품을 보면 정말 짜증날 정도로 쉽고, 자세하게 문서화를 해 놓은 것을 볼 수 있는데.... 역시 문서란... 전혀 모르는 사람도 문서의 내용만 보고 최소한 따라할 수 는 있어야 한다고 생각됩니다.
저도 저번에 책 만든다고 작업을 한 적이 있는데.. 처음 의도와는 달리 잘 되지 않더군요. 남들에게 저의 생각을 글로 전달하는 것이 그리 쉽지많은 않습니다.
Re: 저는
저도 동감하는 부분입니다.
그래서 전에 회사 다닐적에, 팀원들에게 항상 소스코드 1라인당 주석 하나의 원칙을 지키지 않으면 소스를 accept 못하겠다고 했더니 여기저기서 곡소리가 나더군요. :?
To be a rich