Телеграмм чат группы technicalwriters страница 2491

16:46пожаловаться #1

CD

Не согласен. Посмотрите https://python.readthedocs.io/en/latest/

Там часто очень детально написано, как работать с API.

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

16:49пожаловаться #2

CD

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

16:54пожаловаться #3

SR

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

Так и у заказчика, подключающего абстрактную библиотеку, тоже нет единой кодовой базы. Для него это чёрный ящик.

16:55пожаловаться #4

CD

Так и у заказчика, подключающего абстрактную библиотеку, тоже нет единой кодовой базы. Для него это чёрный ящик.

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

16:58пожаловаться #5

SR

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

Верно. Но это дорого.

16:58пожаловаться #6

CD

Верно. Но это дорого.

Почему? Эти тесты вам как разработчику библиотеки тоже сильно пригодятся. Заметьте, вы просто записали ответы на вопросы "как?" в коде вместо того (вместе с тем), чтобы их описывать. Программирование по самому проработанному ТЗ в мире.

17:00пожаловаться #7

SR

Почему? Эти тесты вам как разработчику библиотеки тоже сильно пригодятся. Заметьте, вы просто записали ответы на вопросы "как?" в коде вместо того (вместе с тем), чтобы их описывать. Программирование по самому проработанному ТЗ в мире.

Потому что покрытие тестами это по Замятину.

Есть примеры успешной реализации подобного именно в смысле публичного применения?

17:44пожаловаться #8

CD

Потому что покрытие тестами это по Замятину.

Есть примеры успешной реализации подобного именно в смысле публичного применения?

В некотором смысле - да, потому что примеры кода в документации это оно и есть.

17:44пожаловаться #9

SR

В некотором смысле - да, потому что примеры кода в документации это оно и есть.

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

17:46пожаловаться #10

CD

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

У меня есть еще одно свидетельство. Подумайте о последней проблеме, которая у вас возникала. Представьте, что вы задали вопрос гуглу. Скажите, ответ нашелся в документации или на StackOverflow? Как вы думаете, какое примерно соотношение количества вопросов по python на SO и в их "учебнике"?

17:48пожаловаться #11

SR

У меня есть еще одно свидетельство. Подумайте о последней проблеме, которая у вас возникала. Представьте, что вы задали вопрос гуглу. Скажите, ответ нашелся в документации или на StackOverflow? Как вы думаете, какое примерно соотношение количества вопросов по python на SO и в их "учебнике"?

Тут всё ещё проще: 1) Нельзя задать вопрос в их учебнике. 2) Большое количество вопросов лишь дополняет, но не заменяет учебник. На SO почти нет простых вопросов по питону. А по pandas их *полно*. Почему? Потому что документация пандас написана хуже.

18:47пожаловаться #12

CD

Тут всё ещё проще: 1) Нельзя задать вопрос в их учебнике. 2) Большое количество вопросов лишь дополняет, но не заменяет учебник. На SO почти нет простых вопросов по питону. А по pandas их *полно*. Почему? Потому что документация пандас написана хуже.

А почему вы вообще ориентируетесь на простые вопросы? Ваши типичные пользователи первый раз видят вашу систему?

19:33пожаловаться #13

SR

А почему вы вообще ориентируетесь на простые вопросы? Ваши типичные пользователи первый раз видят вашу систему?

Именно потому что документация всё же отвечает на общие вопросы. Как вы говорили, невозможно покрыть все случаи. Можно их уменьшить, снизив нагрузку на поддержку.

А частные вопросы обычно решаются частным порядком. Для этого есть поддержка. Разных уровней.

21:36пожаловаться #14

CD

Именно потому что документация всё же отвечает на общие вопросы. Как вы говорили, невозможно покрыть все случаи. Можно их уменьшить, снизив нагрузку на поддержку.

А частные вопросы обычно решаются частным порядком. Для этого есть поддержка. Разных уровней.

Мы же согласимся, что справочник - отдельно, учебник - отдельно, перекрестные ссылки и именно справочник обязателен?

21:37пожаловаться #15

SR

Закончим на этом, не то будет перебор. Здесь есть ваша правда, несомненно.

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

Искушённый пользователь всё поймёт из заголовочных файлов, а неискушённый --- не сможет найти ответы на свои вопросы.