C# :: Lecture & TIPs VB :: Lecture & TIPs

Visual Studio Team Services 활용하기 (프로젝트 관련 기술 문서 편집)

안녕하세요, HappyBono 인사드립니다!

며칠 전 Markdown 을 이용한 ReadMe 문서 작성법 에 대해 알아보았었습니다. 개발자 간의 협업을 초점으로 제공되는 서비스인 Visual Studio Team Services 에서도 README 문서와 같은 기술 문서들을 편집 할 수 있는 도구를 제공하는데요, 이번 시간에는 Visual Studio Team Services 에서 여러가지 종류의 기술 문서들을 편집하는 방법에 대해 알아보도록 하겠습니다.

 

들어가기 전에…

README 문서는 다른 개발자들이나 사용자들이 프로젝트를 발견했을 때 제일 처음 접하는 문서입니다. 대부분의 사용자는 README 문서를 읽는 것만으로 이 프로젝트를 좀 더 탐색할지, 다른 프로젝트를 찾아볼지 결정합니다. 그렇기 때문에 README 문서 작성은 오픈소스 공개를 준비하거나 협업하는 데에 있어서 매우 중요한 과정입니다.

README 문서를 작성할 때 특별히 준수해야 하는 규칙은 없지만 사용자의 이해를 돕기 위해 다음과 같은 내용은 필수로 포함하는 것이 좋습니다.

프로젝트의 목적 및 용도 : 프로젝트에 대해 간단하게 설명하는 내용을 포함합니다.

  • 이 프로젝트는 무엇을 위한 것인가?
  • 어떤 문제를 해결할 수 있는가?
  • 왜 이 프로젝트가 유용한가?
  • 어떤 사람들이 이 프로젝트를 사용하면 좋은가?
  • 이 프로젝트는 어떻게 작동하는가?
  • 프로젝트를 시작하는 방법 : 프로젝트를 처음 사용하기 위해 필요한 내용을 포함합니다.
  • 프로젝트를 설치, 사용하기 위해 필요한 전제조건이 있는가?
  • 어떻게 설치, 사용, 테스트하는가?
  • 설치 가이드 문서는 어디에 있는가?
  • 저작권, 라이선스 정보 : 프로젝트의 사용 범위 및 조건을 설명하는 내용을 포함합니다.
  • 어떤 라이선스로 배포되는가?
  • 상세한 라이선스 정보는 어디에서 확인할 수 있는가?
  • 프로젝트를 사용함에 있어 제약 조건이 있는가 (특허, 상업적 사용)?
  • 외부 리소스 정보 : 프로젝트 내에 포함된 외부의 코드나 리소스의 정보를 포함합니다.
  • 각각의 출처 및 배포 라이선스는 무엇인가?

이러한 질문 이외에도 프로젝트에 기여하는 Contribution 에 따른 절차나 버그 신고 방법, 사용자 질문을 올리는 방법 등에 대한 정보를 포함할 수도 있습니다.

아직 프로젝트의 완성도가 낮다고 생각되어 외부의 프로젝트에 대한 기여를 받고 싶지 않다는 이유로 README 문서를 포함하지 않는 경우들도 존재하는데요, README 문서를 통해 사용자들에게 이러한 의도를 안내하는 경우, 보다 편리하게 프로젝트를 운영할 수 있습니다.

최근에는 전 세계를 대상으로 오픈소스 프로젝트를 공개하면서 다양한 언어로 README 문서를 제공하기도 합니다. 만약, 외국어로 README 문서를 작성할 수 있는 시간이 부족하다면, 오픈소스로 공개한 이후에 다른 언어로 번역하는 도움이 필요하다고 알림으로서 외부로부터 프로젝트에 대한 기여를 받을 수도 있습니다.

 

Visual Studio Team Services 에서 README 문서 추가하기

앞에서 설명한 바와 같이,  README 문서는 다른 개발자 사용자들이 프로젝트를 발견 했을 때 제일 처음에 접하는 문서인 만큼, 기본 값으로 Visual Studio Team Services (http://www.visualstudio.com/) 에 로그인 하면 보이는 Main 화면에서 README 문서를 볼 수 있도록 배치되어 있습니다.

 

1. README 문서를 추가하시려면 [Create README] 버튼을 클릭하세요.

 

Tech_Doc-001

 

2. README 문서에 대한 텍스트 에디터가 표시되는데요, 본문을 입력하시고 [Check-in] 버튼을 클릭합니다.

 

Tech_Doc-002

 

3. 코드 저장소 (Repository) 에 표시될 변경 내역 TextBox 에 입력하신 후 [Check in] 버튼을 클릭합니다. ([TIP] Markdown 을 이용한 ReadMe 문서 작성법 에서 기술했었던 Markdown 문법들을 완벽하게 지원합니다.)

 

Tech_Doc-003

 

4. 이제 체크인 (Check-in) 을 성공적으로 마치시게 되면, 다음과 같이 잘 정리된 README 문서를 보실 수 있습니다.

 

Tech_Doc-004

 

 

Visual Studio Team Services 에서 Wiki (프로젝트 기술 관련) 문서 집필하기

맨 상단의 Wiki 탭을 클릭하여 진입하신 화면 중앙에 표시되는 [Create Wiki] 버튼을 클릭합니다.

 

Tech_Doc-007

 

2. Wiki 문서 편집 화면이 다음과 같이 표시되는데요, Wiki 문서의 제목과 본문을 Markdown 문법에 맞추어 집필 / 편집 하신 다음, 상단의 [Save] 버튼을 클릭하여 작성하신 문서를 저장하시면 프로젝트에 대한 기술 문서 편집이 최종적으로 완료되게 됩니다.

 

Tech_Doc-008

 

Main 화면에 표시되는 문서 변경하기.

1. 일반적으로 Visual Studio Team Services 의 기본 값으로는 Main 화면에 README 화면이 표시되도록 설정되어 있습니다. 이를 화면 중간의 [Change] 버튼을 클릭하여 설정을 변경하실 수 있습니다.

 

Tech_Doc-005

 

2. README 문서와 Wiki (프로젝트 기술) 문서의 첫 페이지 중 어느 화면을 표시할 지 선택하신 후, [Change] 버튼을 클릭하시면 Main 화면에 보여지는 문서가 변경되어지게 됩니다.

 

Tech_Doc-006

 

Wiki (프로젝트 기술 문서) 작성 권한 설정하기.

1. 사내 동료 혹은 친구들과 함께 프로젝트를 기획 / 개발하는 경우 추가적인 보안 설정으로 권한을 부여하여야 기술 문서 편집도 함께 하실 수 있습니다. 다른 동료분들이나 친구와 함께 협업하여 편집하려면 페이지 상단에 위치한 [More] 버튼을 클릭하신 후에 나타나는 팝업식 메뉴에서  [Wiki Security] 항목을 클릭합니다.

 

Tech_Doc-009

 

2. 보안 설정 창이 화면에 표시되는데요. 물론 그룹별 관리도 가능하지만, [Add] 버튼을 이용해 사용자를 개별적으로 추가 할 수도 있습니다. (단, 추가하시는 대상이 본 프로젝트에 대한 구성원으로 초대 / 가입되어 있어야만 가능합니다.)

 

Tech_Doc-010

 

3. 이렇게 등록된 개별 구성원의 성명 혹은 전자 메일 주소를 입력하여 Wiki (프로젝트 기술 문서) 를 공동 편집하는 권한을 부여할 수 있습니다.

 

Tech_Doc-011

 

4. 마지막으로 Wiki (프로젝트 기술 문서) 의 공동 편집 권한해당 구성원에게 올바르게 부여되었는지 확인 하신 후 Close 버튼을 클릭하여 마무리 합니다.

* 공동 편집 권한은 아래 스크린 샷 처럼 Contribute, Manage Note 와 Read 항목이 Allow (허용) 되어 있어야만 부여됩니다.

 

Tech_Doc-012

 

여기까지 README 문서와 프로젝트 관련 기술 문서를 편집하는 방법에 대해 알아보았습니다.  다음 포스팅에서는 Visual Studio Team Services 에서 개발된 앱을 Test 하고 Build 하는 내용에 대해 다루어보도록 하겠습니다.

긴 글 읽어주셔서 고맙습니다.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s