Изучая новый язык программирования, фреймворк или даже просто пытаясь найти помощь в том, как заставить часть моего проекта работать, я всегда просматриваю несколько блогов/сайтов/статей в поисках какого-то ответа. Если он находится в Stack Overflow, обычно я могу найти помощь. Но когда это на частном сайте, я склонен снова и снова сталкиваться с одними и теми же проблемами.
Вот четыре вещи, которые должны содержаться в каждом руководстве для разработчиков:
- Дата. Пожалуйста, ради Бога, назовите дату. Платформы и фреймворки постоянно меняются, и если вы не укажете дату в своем посте, будет трудно понять, будет ли ваш ответ полезен или нет. Это может показаться хорошим ответом, я пробовал, но это не сработало. Затем я провожу дополнительные исследования и узнаю, что ваш способ устарел. Это не круто. И я думаю, что этого можно легко избежать.
- Хорошее название и краткое описание руководства. Я сталкивался с сайтами, которые это делают, и ура им, но те, которые этого не делают, вводят в заблуждение. И я думаю, это потому, что название может звучать так, как будто оно пытается что-то решить, но в итоге получается нечто совершенно отличное от того, что вы хотите. Для резюме просто напишите пару предложений о том, какие цели или результат туториала.
- Укажите, какой язык вы используете. Я знаю, что довольно легко прокрутить до блоков кода и увидеть язык, или если вы используете платформу, вы знаете, на чем она написана, но если вы даете решение для интеграции API, оно может быть на множестве языков, так что скажите это сразу или, еще лучше, укажите это в заголовке.
- Прокомментируйте свой код. Многие объясняют код в абзаце под блоком кода, но было бы очень полезно и быстрее для тех, кто читает, иметь возможность просто читать комментарии в коде. В конце концов, у вас есть разработчики, которые читают эту вещь, и есть вероятность, что они не читают слово в слово того, что вы написали.
Все четыре из них помогают читателю понять, о чем ваш пост/статья/написание. Если это не то, что ищет читатель, он может быстро узнать и двигаться дальше. Будьте ясны и прямолинейны, это сделает ваши статьи намного лучше.
Спасибо за чтение. Я уверен, что в этот список можно добавить еще что-то, дайте мне знать, если я что-то упустил, и как вы относитесь к четырем выше.
Фото Стэнли Дай на Unsplash
Первоначально опубликовано на yeddiecodes.wordpress.com 1 октября 2017 г.
