서술 스타일(writing style)

핵심 목표

The main goals for this manual are as follows:

사용자에게 맞추기

The manual is written for people educated in computer graphics, who understand the basics of 3D and/or know other 3D software. While some areas of computer graphics are highly technical, this manual shall be kept understandable by non-technical users.

높은 완성도

The manual provides detailed functional description of all features, tools and options in Blender. While there is a canonical source of truth for each of Blender’s key areas, this does not mean we have to document every small detail. The manual should provide information on what a feature is, how to use it, and its purpose. More background information should be provided when necessary to give deeper understanding of a 3D pipeline.

간결하게

Computer graphics is an incredibly interesting field. There are many rules, exceptions to those rules, and interesting details. However, expanding into details can add unnecessary content; therefore, keep the text concise and relevant to the end user.

유지보수성

Keep in mind that Blender has frequent releases, so try to write content that will not have to be redone the moment some small change is made. This also helps a small documentation community maintain the manual.

내용 지침

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

규칙들

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

  • Use American English (e.g: modeling and not modelling, color and not colour) also for formatting numbers (e.g: 2,718.28 and not 2 718,28).

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

  • Keep sentences short and clear.

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

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

하지 말 것들

  • Avoid writing in the first person perspective, about yourself, or about your own opinions.

  • 모호한 단어(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 and become quickly outdated.

  • 버그를 쓰지 마세요.

    Blender often has hundreds of bugs fixed between releases, so the manual cannot be expected to keep up.

    Issues that are known to the developers and are not going to be resolved before the next release can be documented as Known Limitations. In some cases, it may be best to include them in the troubleshooting section.

  • Avoid product placements, e.g. unnecessarily promoting software or hardware brands. Keep content vendor-neutral where possible.

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

    (E.g. explaining how mesh smoothing algorithms work is unnecessary, but the blending types of a Mix node do need a mathematical explanation.)

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

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

  • Avoid listing every option in a menu, such as frame rates.

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

  • 블렌더 버전이 바뀌면서 생긴 변화는 적지 마세요. 배포 기록(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
   Distorts vertices with an image.
   Similar to Bump Mapping, but operates on the mesh's geometry.
   The mesh must have 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 line interpolated between Control Vertices.
   Common types include Bézier and NURBS.