Чому стільки бібліотек не мають / поганої документації? [зачинено]

Так само, як проекти з відкритим кодом можуть бути успішними без документації про їх дизайн чи архітектуру? питання, мені цікаво: Чому стільки бібліотек так не вистачає в документації для кінцевих користувачів?

Мій погляд такий:

1. Більшість усіх згодні з тим, що читати вихідний код складніше, ніж писати вихідний код.
2. Без документації потрібно прочитати вихідний код бібліотеки, щоб використовувати цю бібліотеку.
3. Тому використання незадокументованої бібліотеки - це більше роботи, ніж просто відтворення бібліотеки з нуля.
4. Як результат, якщо ви хочете, щоб люди користувались вашою бібліотекою, вам краще, переконайтесь, що це документально підтверджено.

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

О, зауважте, що коли я кажу документацію, я маю на увазі реальну документацію. Без котлоану Sandcastle / Javadoc / Doxygen.

Я думаю, що ви здебільшого відповіли на власне запитання: адже в більшості випадків розробники просто не турбуються. Проблема особливо поширена у волонтерських проектах.

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

У типовому випадку те, що написано, має огляд дуже високого рівня ("Це бібліотека для класних робіт!"), А потім опис дуже низького рівня (тип та опис кожного параметра, який потрібно передати кожній функції). На жаль, рідко існує проміжний рівень щодо загальної теорії того, як все має працювати, як штуки поєднуються між собою тощо. Багато чого з цього пояснюється тим, що розробники часто не намагаються сформувати, раціоналізувати чи зрозуміти їх код на конкретному рівні деталізації. Принаймні, в деяких випадках, які я бачив, розробники, яких просили написати документацію на цьому рівні, вважають це досить проблематичним - до того, що багато хто хотів переписати код, щоб було більш організовано і простіше пояснити на цьому рівні докладно.

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

Я думаю, що іноді це відбувається через те, що розробник настільки загорнутий у код, що йому / їй "очевидно", як це працює, і вони не можуть зрозуміти, чому це не було б очевидно для інших. Так само навантаження на веб-сайтах продуктів говорить про те, наскільки чудовим є їхній продукт, але насправді не кажіть, що він робить!

Ви самі вказали на відповідь:

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

Як програмісти, ми насолоджуємося написанням коду, але мало хто з нас також насолоджується написанням документації.

Хоча будь-який хороший кодер знає цінність хорошої документації, для її належного виконання потрібно також досить багато часу. Оскільки це не приємно і займає багато часу, його кладуть у купу "робити пізніше", щоб вона ніколи не була зроблена на задовільний рівень.

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

Написання документації - це навичка. Як і всі навички, це вимагає практики. Час і зусилля, які ми витрачаємо на написання коду, негайно окупилися. Ми можемо побачити нову функцію, виправлену помилку, покращену швидкість. Написання документації має відстрочку. Це допомагає в довгостроковій перспективі, оскільки новим людям потрібно працювати над кодом або якщо ми повернемося до роботи над кодом місяці або роки останні. Цілком природно, що ми зосереджуємось на короткостроковій перспективі.

На мій погляд, вміння писати гарну документацію - це одна з ключових рис, яка відрізняє великих програмістів від посередніх програмістів.

Особа, яка найкраще кваліфікується для написання документації, також є особою, яка має найменшу мотивацію для цього:

він (або вона):

• передусім обслуговувачем бібліотеки, а не користувачем. Тож чим менша і простіша бібліотека, тим простіша її робота. Збереження половини роману, крім коду, лише ускладнює його роботу,
• він знає бібліотеку зсередини, тому йому не потрібна документація,
• він програміст, він хоче писати код, а не документацію.

Я не можу придумати того, хто має меншу ймовірність "Хм, я дійсно повинен витратити кілька годин на написання належної документації для цього". Навіщо йому?

І звичайно, це, мабуть, не допомагає, що існує ця міська легенда, що коментарі в стилі доксигену - це все, що вам потрібно в документації.

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

Документація? Нам не потрібна смердюча документація!

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