Я трачу много времени на написание кода для таких вещей, как моды для видеоигр, Photoshop и API-интерфейсы веб-сайтов, которые, скорее всего, будут использовать непрограммисты. Поэтому я часто обнаруживаю, что выражаю колебания, прежде чем я буду готов развернуть сценарии и ботов, пока моя документация не станет достаточно надежной, чтобы ее мог понять любой читающий.
Действительно идти шаг за шагом
Вникайте в мельчайшие детали того, как запускать вашу программу, и рассматривайте каждый сделанный вами щелчок мыши как неотъемлемый шаг. Я часто записываю, как запускаю программу, а затем пересматриваю, записывая свои указания, чтобы ничего не пропустить. Это хороший способ убедиться, что вы пишете полные указания, не прерывая поток, пока вы выполняете свою программу самостоятельно.
Учитывайте различия в системах
Не всем из нас повезло иметь несколько компьютеров и операционных систем для тестирования. Теперь я не предлагаю вам покупать новый компьютер или настраивать виртуальную машину для запуска всей программы, но подумайте, как кто-то в другой ОС будет запускать вашу программу, и постарайтесь решить эти проблемы заранее.
Я работаю на MacOS, в которую встроено множество инструментов программирования, но когда я создавал свой первый сценарий Photoshop, я попросил друга, у которого есть компьютер с Windows, попробовать его на ее машине. У нее была другая ОС и другая версия Photoshop, так что потребовалось некоторое устранение неполадок, чтобы запустить его, но когда он, наконец, заработал, я знал, какие шаги мне нужно будет включить в свою документацию, чтобы получить пользователя Windows на на той же странице, что и мой сценарий.
Не бойтесь быть неформальным
Слишком много формальностей может отпугнуть непрограммиста от использования вашей программы, даже если вы думаете, что это самая простая вещь в мире. Я часто включаю такие вещи, как «Откройте вашу командную строку (обычно это будет черный экран с белыми или зелеными буквами, как то, что хакеры используют в CSI)». Эти случайные отступления могут сделать читателя удобным и помочь прояснить концепции. Хотя это не подходит для профессиональной документации, когда вы пытаетесь объяснить новичку код, полезно сделать так, чтобы он чувствовал себя комфортно с этими инструментами.
Рассмотрите международную аудиторию
Развертывание вашего кода в Интернете означает, что кто угодно и где угодно будет иметь к нему доступ! Я рекомендую писать простыми словами, а предложения краткими. Вы не обязаны переводить свой код на разные языки, просто старайтесь, чтобы язык был понятным. Это, вероятно, поможет вашей нетехнической англоязычной аудитории в любом случае не усложнять вещи.
Будьте готовы к вопросам
Я всегда рекомендую пользователям попытаться устранить неполадки самостоятельно, прежде чем обращаться ко мне, потому что я считаю, что вы узнаете гораздо больше, исправляя проблемы самостоятельно, но если вы развертываете код для общего пользования, вы должны быть готовы к ответить на некоторые вопросы. Я обычно включаю контактную информацию в код, чтобы люди могли обращаться ко мне с вопросами, особенно в отношении кода, который я хочу использовать для более широкой аудитории (например, сценариев Photoshop), или кода, созданного для определенных веб-API (например, моих ботов в Твиттере). Обычно я приспосабливаю эту контактную информацию к тому, для чего предназначена программа, например, оставляю свои учетные данные Twitter в кодах для Twitter API и т. Д.
Не бойтесь документации
Как английский программист, ставший программистом, я, вероятно, должен иметь самую чистую доступную документацию, но мне не привыкать к случайным «пустым мозгам», когда дело доходит до написания моих README
. Написание хорошей документации требует практики, но это один из самых ценных навыков, который программист должен стремиться улучшить.