오라리의 구글 소프트웨어 공학 문서

이 글의 개요

작년 연말에 일본 올리브에서 출판됐어요.
구글의 소프트웨어 공학 관련 문서의 장과 절을 잊어버리기 위해 개인적으로 내용을 총결하였다.
책의 내용에 저의 주관과 감상을 추가한 것이기 때문에 시간이 있는 사람은 직접 책을 보는 것을 추천합니다.
팀 건설과 시험과 관련된 내용 등 매우 참고 가치가 있는 내용을 읽어주세요(아직 다 읽지는 못했지만).

팀 관리에 대한 전제와 과제감

문서를 제작하는 개발자는 제작의 은혜를 거의 받지 않으며, 기본적으로 독자는 그것의 은혜를 받을 것이다

만들어진 효과에 따라 새로운 멤버가 들어오거나 일정 시간이 지난 후 확인할 때 장기적인 효과가 있다

문서는 그 코드를 쓴 엔지니어가 만들었다.그것을 효과적으로 쓰기 위해서는 적당한 도구와 격려가 필요하다. (귀찮기 때문에)

문서는 단기간에 매우 번거로운 작업이지만 장기적인 관점에서 보면 제작 원가에 충분한 효과가 있다

고정 목표를 실현하기 위해서는 프로세스를 기존의 작업 프로세스에 도입할 필요가 있다

개발진이 다른 사람이 쓴 코드를 수정할 때 고품질의 문서가 없는 것은 과제이다

예:

이 문서가 최신인가요?

특정 절차가 잘못될 수 있는데 어떻게 하면 좋을까요?

이 방법이나 유형을 사용할 때의 영향이나 주의사항은?

한마디로 "단기적인 효과를 보기 어렵기 때문에 까다로운 작업이라는 점을 이해한 토대에서 구조화·동기화가 필요하다"며 강한 공감을 불러일으키는 과제감이다.

이런 과제에 대해 어떻게 해야 합니까?

코드와 마찬가지로 문서에도 소유자가 있어야 한다

소유자가 명확하지 않으면 불안정하게 유지보수

Google에서도 코드 검사와 마찬가지로 문서 검사

3개월 동안 확인되지 않은 문서의 소유자에 대해 메일을 통해 알림을 주는 구조

코드 파일의 첫머리에 1-2 단락에서 이 코드가 무엇을 하는지 개요를 설명해야 한다

클래스 또는 함수로서의 설명

XX 문자열을 반환합니다.int를 매개 변수로 주면 변환 후 문자열을 되돌려줍니다.그렇지 않으면 ZZZ의 예외

가 발생합니다.

👆이렇게 하면 한 단락으로 개괄적으로 쓸 수 있다

한마디로'규칙화와 구조화가 중요하다'는 것이다.

문서의 Tips

프로그램에 대한 문서는 전통적으로 "How?"다른 누구를 겨냥한 건지.이 문서의 목적은 무엇입니까?등 많은 경우에 기재되지 않았다.

기술 문서에서도 독자의 이해성을 높이기 위해서는 상기 How 이외의 개요와 목적의 기재가 필요하다

문서에 기재해야 할 내용(예제)

- 目的
    - このドキュメントは、〇〇の開発環境であるPython3.9の仮想環境を作成し、githubにCommitができるまでの手順を記載している。
- 想定読者
    - 〇〇プロダクトに新しくジョインした新メンバーが環境構築を行うために読むことを想定
- 必要な情報の場所
    - Git repoのリンクなど
- 最終更新者
    - パブロ（更新者名）
- 最終更新日
    - 2022/04/01

총결산

나는 문서를 만드는 것이 당연하다는 것을 다시 한 번 깨달았다.단기적으로는 제작 원가에 신경을 많이 쓰고 골칫거리가 되는 것도 당연하다.
그러나 팀 구성원 증가와 멤버 교체 발생 등에 따라 장기적 관점에서 불가결하거나 빠질 수 없어 원가에 충분한 효과가 있음을 다시 느꼈다.
주관적인 생각이지만 팀워크 효율성 높은 대안으로

코드 검사 시간에도 문서 검사

문서 소유자 파악

유지 관리 메커니즘(Google의 경우 알림 메시지) 포함

누구에게 쓴 문서/명목의 범위

미개발 경험의 새로운 구성원과 숙련도가 높은 구성원은 이해에 필요한 정보량이 다르다

그걸 깨닫게 되면 팀으로서의 장기적 강도가 높아지겠죠.이 기사를 읽고 관심 있는 사람은 책을 읽으세요.