Как написать руководство по NumPy#
Руководства сразу переходят к сути – они
ответить на конкретный вопрос, или
сузить широкий вопрос до сфокусированных вопросов, среди которых пользователь может выбрать.
Незнакомец спросил дорогу...#
«Мне нужно заправить машину.»
Дайте краткий, но явный ответ#
«Три километра/мили, поверните направо на Хейсид-роуд, это будет слева.»
Добавьте полезные детали для новичков («Просёлочная дорога», даже если это единственный поворот на трех км/милях). Но не нерелевантные:
Также не давайте указания с Маршрута 7.
Не объясняйте, почему в городе только одна заправочная станция.
Если есть связанный фон (руководство, объяснение, ссылка, альтернативный подход), обратите внимание пользователя с помощью ссылки («Направления от Маршрута 7», «Почему так мало заправочных станций?»).
Делегировать#
«Три км/мили, поверните направо на Hayseed Road, следуйте указателям.»
Если информация уже задокументирована и достаточно краткая для руководства, просто дайте ссылку на неё, возможно, после введения («Три км/мили, поверните направо»).
Если вопрос широкий, сузить и перенаправить его#
«Я хочу посмотреть достопримечательности.»
The Посмотреть достопримечательности how-to должен ссылаться на набор более узких how-to:
Найти исторические здания
Найдите смотровые площадки
Найти центр города
и они, в свою очередь, могут ссылаться на ещё более узкие руководства – так что центральная страница может ссылаться на
Найти здание суда
Найти здание мэрии
Организуя руководства таким образом, вы не только показываете варианты для людей, которым нужно сузить свой вопрос, но и предоставляете ответы для пользователей, которые начинают с более узких вопросов («Я хочу увидеть исторические здания», «Как пройти к ратуше?»).
Если шагов много, разбейте их#
Если руководство содержит много шагов:
Рассмотрите возможность вынесения шага в отдельное руководство и ссылки на него.
Включите подзаголовки. Они помогают читателям понять, что будет дальше, и вернуться к тому месту, где они остановились.
Зачем писать руководства, если есть Stack Overflow, Reddit, Gitter…?#
У нас есть авторитетные ответы.
Руководства, которые делают сайт менее пугающим для не-экспертов.
Руководства привлекают людей на сайт и помогают им обнаружить другую информацию, которая здесь есть.
Создание руководств помогает нам увидеть удобство использования NumPy новыми глазами.
Разве how-tos и tutorials — не одно и то же?#
Люди используют термины «how-to» и «tutorial» взаимозаменяемо, но мы проводим различие, следуя Daniele Procida's таксономия документации.
Документация должна соответствовать тому, где находятся пользователи. Руководства предоставляют информацию для выполнения задачи; пользователь хочет шаги для копирования и не обязательно хочет понимать NumPy. Учебные пособия представляют собой общую информацию; пользователь хочет получить представление о каком-то аспекте NumPy (и снова, может или не может интересоваться более глубокими знаниями).
Мы различаем как учебные пособия, так и практические руководства от Объяснения, которые представляют собой углубленные погружения, предназначенные для понимания, а не для немедленной помощи, Ссылки, которые предоставляют полные, авторитетные данные о некоторой конкретной части NumPy (например, его API), но не обязаны давать более широкую картину.
Для получения дополнительной информации об учебных пособиях см. Научитесь писать учебник по NumPy
Является ли эта страница примером руководства?#
Да – до разделов с заголовками-вопросами; они объясняют, а не дают указания. В руководстве это были бы ссылки.