Как написать руководство NumPy по «как делать»

Незнакомец попросил указания…

«Мне нужно заправить машину.»

Дайте краткий, но ясный ответ

• «Три километра/мили, поверните направо на дорогу Hayseed, она слева.»

Добавьте полезные детали для новичков («дорога Hayseed», даже если это единственный съезд на расстоянии трех км/миль). Но не включайте не относящиеся к делу:

• Не давать также указания с трассы 7.
• Не объяснять, почему в городе всего одна заправочная станция.

Если есть связанная информация (учебник, объяснение, справочник, альтернативный подход), обратите на нее внимание пользователя с помощью ссылки («Указания с трассы 7», «Почему так мало заправочных станций?»).

Делегировать

• «Три км/мили, поверните направо на дорогу Hayseed, следуйте указателям.»

Если информация уже задокументирована и достаточно лаконична для руководства по «как делать», просто дайте ссылку на нее, возможно, после введения («Три км/мили, поверните направо»).

Если вопрос широкий, сузьте и перенаправьте его

«Я хочу посмотреть достопримечательности.»

Руководство по «как посмотреть достопримечательности» должно ссылаться на набор более узких руководств по «как делать»:

• Найти исторические здания
• Найти живописные смотровые площадки
• Найти центр города

и эти руководства, в свою очередь, могут ссылаться на еще более узкие руководства – например, страница центра города может ссылаться на

• Найти суд
• Найти мэрию

Организуя руководства по «как делать» таким образом, вы не только показываете варианты для людей, которым нужно сузить свой вопрос, но и предоставляете ответы для пользователей, которые начинают с более узких вопросов («Я хочу посмотреть исторические здания», «В какую сторону находится мэрия?»).

Если шагов много, разбейте их на части

Если в руководстве по «как делать» много шагов:

• Подумайте о том, чтобы выделить шаг в отдельное руководство по «как делать» и связать его с ним.
• Включите подзаголовки. Они помогают читателям понять, что будет дальше, и вернуться к тому месту, где они остановились.

Зачем писать руководства по «как делать», если есть Stack Overflow, Reddit, Gitter…?

• У нас есть авторитетные ответы.
• Руководства по «как делать» делают сайт менее сложным для новичков.
• Руководства по «как делать» привлекают людей на сайт и помогают им узнать другую информацию, которая здесь есть.
• Создание руководств по «как делать» помогает нам взглянуть на удобство использования NumPy новыми глазами.

Разве руководства по «как делать» и учебники не одно и то же?

Люди используют термины «руководство по «как делать»» и «учебник» взаимозаменяемо, но мы проводим различие, следуя таксономии документации Даниэля Проциды таксономия документации.

Документация должна встретить пользователей там, где они находятся. Руководства по «как делать» предлагают информацию для выполнения задачи; пользователь хочет шаги для копирования и не обязательно хочет понять NumPy. Учебники содержат информацию, позволяющую познакомиться с некоторым аспектом NumPy (и опять же, пользователь может или не может заботиться о более глубоких знаниях).

Мы различаем как учебники, так и руководства по «как делать» от объяснений, которые представляют собой глубокие погружения, призванные обеспечить понимание, а не немедленную помощь, и справочников, которые предоставляют полные, авторитетные данные о какой-либо конкретной части NumPy (например, его API), но не обязаны представлять более широкую картину.

Подробнее об учебниках см. Научитесь писать учебник NumPy

Является ли эта страница примером руководства по «как делать»?

Да – до тех пор, пока не дойдете до разделов с вопросами в заголовке; они объясняют, а не дают указания. В руководстве по «как делать» это были бы ссылки.