소프트웨어 환경 문서 체크리스트 [닫기]

Question

나는 보험회사에서 일해요.우리는 거의 150명에 달하는 인력과 일부 제공업체(대부분 아웃소싱 및 맞춤형 앱)로 구성된 자체 개발 부서를 보유하고 있습니다.우리 회사에서 우리 팀은 비기능적 논리 라이브러리라고 부르는 것을 만들었습니다.즉, 우리 부서의 모든 개발팀에게 수평적인 일을 처리하는 소프트웨어 라이브러리입니다.보안, 웹 서비스, 로깅, 메시징 등.대부분의 도구 또는 이러한 도구는 처음부터 만들어지거나 사실상의 표준을 적용하여 만들어졌습니다.예를 들어, 우리의 로거는 로깅 메시지를 DB에 저장하는 Log4J 기반의 어펜더입니다.또한 애플리케이션에서 사용할 라이브러리(예: 사용할 웹 서비스용 프레임워크)를 정의합니다.우리는 조직 전체에서(일부 Websphere 애플리케이션 서버 포함) JavaEE와 Oracle AS를 거의 사용하고 있습니다.

이러한 프로젝트의 대부분은 아키텍처(사용 사례, UML 다이어그램 등)가 문서화되어 있으며 일반적으로 생성된 문서를 사용할 수 있습니다.이제 우리가 본 것은 사용자들이 때때로 우리가 제공하는 라이브러리를 사용하기 어렵고 끊임없이 질문을 하거나 단순히 사용하지 않는다는 것입니다.

그래서 우리는 그들을 위해 보다 친숙한 문서를 생성할 계획입니다. 따라서 제 질문은 다음과 같습니다.소프트웨어 문서에 포함되어야 하는 모범 사례나 체크리스트는 무엇입니까?

내 마음에 뭔가가 떠오른다 :

1. API 참조 가이드
2. 빠른 시작 튜토리얼
3. API 생성 문서.
4. 검색이 가능해야 합니다
5. 웹 액세스

또 무엇이 있어야 합니까?또한 귀하의 경험을 바탕으로 이러한 유형의 문서를 유지(최신 상태로 유지)하고 게시하는 가장 좋은 방법은 무엇입니까?

Answer 1

버전 관리에서도 문서를 유지하세요.

사용자가 어디에서 읽고 있는지 알 수 있도록 모든 페이지에 버전 번호가 있는지 확인하세요.

CI 서버를 가동하고 업데이트 시 라이브 문서 사이트에 문서를 푸시하세요.

코드 검토와 마찬가지로 문서 검토를 수행합니다.

개밥 :)

친절,

단