Написание документации часто важнее, чем написание самого кода. Почему? Ну, а если никто не знает, как использовать ваш код, никто его использовать не будет. Вы должны быть в состоянии объяснить, как работает ваш код и почему он работает именно так. Таким образом, другие разработчики будут знать, как писать код в том же стиле, что и вы. Если вы предоставите примеры того, как вы реализуете свой код, другие поймут контекст, в котором можно использовать ваше программное обеспечение.
Итак, остается вопрос: как написать хорошую документацию? Чтобы получить хороший набор объяснимых концепций, вам нужно сделать несколько шагов:
- Определите самую важную цель, которую люди имеют для вашей части программного обеспечения.
- Определите наиболее важные аспекты вашего программного обеспечения
- Узнайте, какая часть программного обеспечения останется неизменной с этого момента
Вы можете использовать эти три пункта, чтобы определить, ЧТО документировать. Вы можете подумать, что должны все документировать, но это не обязательно так. Вы должны задокументировать то, что вы считаете наиболее важной частью вашего программного обеспечения и что другие будут использовать чаще всего. Когда эти концепции станут кристально ясными, вы сможете задокументировать более скрытые части вашего кода, если это необходимо.
Основные правила хорошей документации
Вы собрали небольшой список вещей для документирования, отлично! Теперь мы можем перейти к той части, где вы начинаете писать. Тем не менее, при написании документации необходимо помнить о некоторых вещах:
- Пишите привлекательную и понятную документацию
- Пишите исчерпывающую документацию
- Пишите документацию, которую можно просмотреть
- Напишите документацию, которая предлагает примеры того, как использовать код
- Напишите документацию, в которой есть повторения, когда это полезно
- Пишите актуальную документацию
- Пишите документацию, в которую легко вносить свой вклад
- Пишите документацию, которую легко найти
Этот список был составлен в прекрасной статье Адама Скотта Восемь правил хорошей документации. Для подробного объяснения каждой из этих концепций я хотел бы указать вам на эту статью.
Эти правила могут показаться очень очевидными, но вы будете удивлены, как часто эти правила не учитываются при написании документации. При объяснении понятий следует использовать очень дружелюбный тон. Вы хотите, чтобы люди читали о вашем программном обеспечении, и вы не должны заставлять их чувствовать себя хуже разработчика из-за того, что они не сразу поняли ваш код. Вы также должны вдаваться в подробности, приводя обширные примеры того, как реализовать программное обеспечение, а не писать одно и то же по десять раз.
Объяснять концепции, не перегружая читателя
Когда вы пишете о своем коде, и есть несколько способов взаимодействия, например, с классом, вам не нужно документировать каждый способ сделать это. Вы можете указать способ реализации программного обеспечения в своих проектах и позволить им изучить другие способы взаимодействия с кодом. Все, что вам нужно сделать, это нарисовать картину и помочь разработчикам понять, как и почему вы решили написать программное обеспечение именно так, как вы это сделали.
Держите документацию в актуальном состоянии
При написании документации вы должны убедиться, что другие могут легко обновлять документацию. Это имеет дополнительное преимущество, заключающееся в том, что новые функции, созданные другими, могут быть задокументированы для вас и других. Это также означает, что документация, скорее всего, будет обновляться по мере использования кода. Нет ничего более разочаровывающего в программном обеспечении, чем документация, которая давно не обновлялась, и все примеры кода больше не похожи на реализации. Будьте в курсе этого, найдите время, чтобы обновить документацию. Окружающие, но и вы сами через несколько месяцев скажут вам за это спасибо.
Убедитесь, что люди могут найти вашу документацию
И последнее, но не менее важное: убедитесь, что вашу документацию можно найти в самом видном месте. Если вы хотите, чтобы ваша документация имела дополнительную ценность, люди должны иметь возможность найти ее и перемещаться по ней. Существует множество примеров отличной документации, где основным приоритетом документации было быстро найти и прочитать документацию. Документация Laravel — одна из таких. Есть и ужасные куски документации, не буду их называть, но они часто автоматически генерируются из кода. Эти автоматически сгенерированные веб-сайты документации охватывают слишком много вопросов и делают это таким образом, что вы можете также прочитать исходный код, потому что, по крайней мере, вы сможете щелкнуть его. Не делайте этого, потому что это вызовет больше вопросов, чем ответов.
Теперь у вас есть несколько основных рекомендаций, которые следует учитывать при написании документации. Так что остается сделать только одно: написать отличную документацию! Вы сделаете себе и другим огромную услугу, если сможете предоставить документацию для своего программного обеспечения. Любой новый код будет соответствовать этой документации, и это позволит вам писать код, а не просто исправлять код, написанный другими. Если у вас есть какие-либо дополнения или вопросы, вы можете связаться со мной в Твиттере в любое время.
Опубликовано: 30 октября 2019 г.
Первоначально опубликовано на https://roelofjanelsinga.com.
