Почему у многих библиотек нет / плохая документация? [закрыто]

Аналогично тому, как проекты с открытым исходным кодом могут быть успешными без документации об их дизайне или архитектуре? вопрос, мне любопытно: почему так много библиотек так не хватает документации конечного пользователя?

Мое мнение таково:

1. Большинство людей согласны с тем, что чтение исходного кода сложнее, чем написание исходного кода.
2. Без документации нужно прочитать исходный код библиотеки, чтобы использовать эту библиотеку.
3. Поэтому использование недокументированной библиотеки - это больше, чем просто воссоздание библиотеки с нуля.
4. В результате, если вы хотите, чтобы люди использовали вашу библиотеку, вам, черт побери, лучше убедиться, что она задокументирована.

Я знаю, что многие разработчики не любят писать документы, и я согласен, что это может быть утомительной работой. Но это важная работа. Я бы даже сказал, что более важно, чтобы у библиотеки была хорошая документация, чем у лучшего в мире интерфейса программиста. (Люди все время используют дерьмовые библиотеки; немногие используют недокументированные библиотеки)

О, учтите, что когда я говорю документацию, я имею в виду настоящую документацию. Не Сандкасл / Javadoc / Doxygen.

Я думаю, что вы в основном ответили на свой вопрос: потому что в большинстве случаев разработчики не будут беспокоиться. Проблема особенно распространена в волонтерских проектах.

Я думаю, что есть еще одна серьезная проблема: во многих случаях разработчики не разработали общую модель работы своей библиотеки (или просто не могут четко сформулировать эту модель). К сожалению, формулирование этой модели и то, как части программного обеспечения сочетаются друг с другом, часто является наиболее важной частью документации.

В типичном случае написанное имеет очень общий обзор («Это библиотека для классных вещей!»), А затем очень низкое описание (тип и описание каждого параметра, передаваемого каждой функции). К сожалению, редко существует промежуточный уровень в общей теории того, как вещи должны работать, как части сочетаются друг с другом и т. Д. Многое из этого восходит к тому факту, что разработчики часто не пытались формировать, рационализировать или понимать их код на этом конкретном уровне детализации. По крайней мере, в некоторых случаях, которые я видел, разработчики, которых просили написать документацию на этом уровне, находили это довольно проблематичным - до такой степени, что многие хотели переписать код, чтобы он был более организованным и легче объяснимым на этом уровне. подробно.

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

Я думаю, что иногда это потому, что разработчик настолько завален кодом, что ему / ей «понятно», как он работает, и они не могут понять, почему это не будет очевидно ни для кого другого. Точно так же множество веб-сайтов о продуктах говорят о том, как прекрасен их продукт, но на самом деле не говорят вам, что он делает!

Вы сами указали ответ:

Я знаю, что многие разработчики не любят писать документы, и я согласен, что это может быть утомительной работой.

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

В то время как любой хороший программист знает ценность хорошей документации, для того, чтобы сделать это должным образом, требуется немало времени. Так как это не доставляет удовольствия и занимает много времени, его помещают в стопку «сделать позже», поэтому он никогда не достигает удовлетворительного уровня.

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

Написание документации - это навык. Как и все навыки, это требует практики. Время и усилия, которые мы тратим на написание кода, немедленно окупаются. Мы видим новую функцию, исправленную ошибку, улучшенную скорость. Написание документации имеет отложенную отдачу. Это помогает в долгосрочной перспективе, так как новым людям нужно работать над кодом или если мы вернемся к работе над кодом спустя месяцы или годы. Вполне естественно, что мы ориентируемся на краткосрочную перспективу.

На мой взгляд, умение писать хорошую документацию это одна из ключевых черт, которая отличает великих программистов от посредственных программистов.

Человек, который лучше всего подходит для написания документации, также является человеком, который имеет наименьшую мотивацию для этого:

он (или она) это:

• в первую очередь сопровождающий библиотеки, а не пользователь. Чем меньше и проще библиотека, тем легче его работа. Ведение половины романа в дополнение к коду только усложняет его работу,
• он знает библиотеку наизнанку, поэтому ему не нужна документация,
• он программист, он хочет писать код, а не документацию.

Я не могу думать ни о ком, кто с меньшей вероятностью скажет: «Хм, я действительно должен потратить несколько часов на написание соответствующей документации для этого». Зачем ему?

И, конечно, это, вероятно, не поможет тому, что есть эта городская легенда о том, что автоматически сгенерированные комментарии в стиле doxygen - все, что вам нужно с точки зрения документации.

Таким образом, даже в тех редких случаях, когда разработчик действительно хочет написать документацию, существует 50/50 шанс, что этот культ «промывает мозги» разработчику, заставляя его думать, что все, что нужно, - это заполнить несколько таких комментариев, рассказывая вам о жемчужинах, как что «функция Foo getFoo()возвращает объект типа Foo, и она используется для получения объекта Foo».

Документация? Нам не нужно вонючей документации!

Я знаю, как работает код, так зачем мне тратить время на документирование своего кода? Кроме того, я должен закончить этот проект к пятнице, и я едва собираюсь сделать его таким, какой он есть ...