서술 스타일(writing style)

핵심 목표

사용설명서가 가지는 목표는 이것들이에요.

사용자에게 맞추기

컴퓨터 그래픽이라는 분야는 곳곳에서 전문적이고 기술적인 것들이 보이지만, 그런 것들에 약한 사람들도 알아듣기 쉽게 쓰여야 해요.

높은 완성도

우리가 기능의 마지막 한 올까지 다 서술할 필요는 없지만, 사용자들이 중요한 기능에 대한 설명을 읽는데 잘 이해가 안 돼서 따로 검색해서 하면서 알아보는 일이 없도록 해야 돼요.

간결하게

컴퓨터 그래픽은 규칙이 많고, 예외도 많아서 재밌는 거죠. 말이 장황해지면 필요없는 내용도 들어갈 테니까, 글은 간결하게 적고 주제에 맞춰 주세요.

유지보수성

블렌더는 자주 출시된다는 사실 아시죠? 작은 변화에 민감한 글은 쓰지 마세요. 사용설명서 팀은 무리해서 일하고 싶지 않답니다.

내용 지침

사용설명서의 서술은 일관적이어야 하니까, 이 페이지에 나열된 규칙들을 기억해 두고 꼭 그래야만 할 이유가 있을 때만 벗어나세요.

규칙들

  • 철자는 꼼꼼히 확인하고 오타를 없애주세요.

  • 미국 영어(american english)를 사용하세요. 예를 들어 modelling이 아니라 modeling, colour이 아니라 color예요.

  • 바른 문법과 적절한 단어를 사용하세요.

  • 문장은 짧고 분명하게, 읽기 편하게 써 주세요.

  • 그 기능이 어디에 어떻게 유용할지 써 주는 건 건 아주 좋아요.

  • 어떤 기능이 어떻게 돌아가는지 잘 모르겠다면, 다른 사람이나 그 기능을 만든 개발자한테 물어보세요.

하지 말 것들

  • 1인칭 표현, 주관적 생각은 쓰지 마세요.

  • 모호한 단어(weasel words) 는 쓰지 마세요.

    "Reloading the file will probably fix the problem"
    "Most people do not use this option because ..."
  • 지나치게 자세한 설명을 쓰지 마세요.

    "Blender has 23 different kinds of modifiers."
    "Enabling previews adds 65536 bytes to the size of each blend-file (unless it is compressed)."

    These details are not useful for users to memorize and they become quickly outdated.

  • 버그를 쓰지 마세요.

    블렌더는 배포할 때마다 100개씩은 버그를 고쳐요. 그러니까 몇 개 쓰는 건 의미가 없어요. 언젠간 사라질 것들이기도 하고요.

    개발자들이 알고 있지만 다음 배포일까지 고쳐지지 않을 문제는 Known Limitations 으로 서술될 수 있어요. 명백하게 도움이 되는 해결법이 있다면 </troubleshooting/index> 에 꼭 적어주세요.

  • 특정 상표나 브랜드를 언급하지 마세요.

  • 더 간단하게 설명할 수 있는데도 수학식과 알고리즘을 동원해서 전문적인 설명을 하지는 마세요.

    부드럽게 하는 알고리즘을 설명할 필요는 없지만, mix 노드처럼 이따금씩 수학적 설명이 필요한 곳도 있어요.

  • 같은 내용을 반복해서 적지 마세요. 한 번만 말하고, 필요하다면 재언급만 하세요.

    보다 나은 소통을 위해 glossary 에서 용어를 새롭게 정의할 수도 있어요.

  • 프리셋들, 프레임수 등 아주 많은 목록을 일일이 나열하거나 비슷한 항복을 반복해서 적지 마세요.

    간단하게 요약될 수 있어요. 그런 것들은 블렌더 화면만 봐도 알 수 있는 것들이구요.

  • 블렌더 버전이 바뀌면서 생긴 변화는 적지 마세요. 배포 기록(release note)이 그래서 있는 거니까요. 지금 쓰는 블렌더에 대해서만 적으면 돼요.

  • 단위나 값의 정확도나 신뢰도가 낮다면, 적지 마세요.

  • 블렌더의 툴팁(tooltip)을 그대로 베껴 적지 마세요. 사용설명서는 툴팁 이상의 것들을 배우기 위해 오는 곳이니까요.

    주석을 남기는 건 자유예요. HTML 페이지에서는 보이지 않지만, 다른 기여자님들에게는 큰 도움이 되죠.

    .. TODO, how does this tool work? ask Joe Blogg's.
    

용어 사전

이 섹션은 특별히 </glossary/index> 섹션에 대해서 다루고 있어요. 블렌더랑 컴퓨터 그래픽에서 많이 쓰이는 단어들의 뜻을 찾아보는 곳이죠.

규칙들

  • 더 많은 관련 정보를 주기 전에 뜻부터 알려주세요.

  • "it is"나 "xyz is"처럼 단어를 다시 언급하는 건 피하세요.

  • 정의에서 그 단어를 다시 쓰지 마세요.

  • 블렌더의 화면(interface)이나 사용설명서에서 찾을 수 없는 단어는 추가하지 마세요.

  • 너무 긴 설명글은 쓰지 마세요. 긴 설명이 필요하다면, 링크로 대신해주세요.

  • 중복된 서술은 안 돼요. 예를 들어 그 항목의 문서에서 이미 정의를 내리고 있거나, 기능의 이름 자체가 뜻이라면 링크를 걸어주거나 아예 용어집에 추가하지 마세요.

  • URL로 된 참고 자료를 뒤에 적어놓을 수도 있어요.

    See also `OpenGL <https://en.wikipedia.org/wiki/OpenGL>`__ on Wikipedia.
    

예시

이 글은

Displacement Mapping
   Uses a grayscale heightmap, like Bump Mapping,
   but the image is used to physically move the vertices of the mesh at render time.
   This is of course only useful if the mesh has large amounts of vertices.

정의가 맨 처음으로 앞당겨져야 해요.

Displacement Mapping
   A method for distorting vertices based on an image.
   Similar to Bump Mapping, but instead operates on the mesh's actual geometry.
   This relies on the mesh having enough geometry.

이 글은

Doppler Effect
   The Doppler effect is the change in pitch that occurs
   when a sound has a velocity relative to the listener.

용어를 다시 사용하지 말아야 해요.

Doppler Effect
   Perceived change in pitch that occurs
   when the source of a sound is moving relative to the listener.

이 글은

Curve
   It is a class of objects.
   In Blender there are Bézier curves and NURBS curves.

대명사로 다시 언급하지 말아야 해요.

Curve
   A type of object defined in terms of a line interpolated between Control Vertices.
   Available types of curves include Bézier and NURBS.