Pecan: Краткое содержание документации

@robkooper и @ashiklom Пытался объединить ваши две идеи схемы. @KristinaRiemer и @bailsofhay будут

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

Когда вы это делаете, глава 41 должна идти раньше 40.

@KristinaRiemer Да, я собираюсь просто

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

Ссылка с @infotroph на документацию: https://www.divio.com/blog/documentation/

Ссылка с @infotroph на документацию: https://www.divio.com/blog/documentation/

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

• учебные пособия для обучения новичков тому, что делает ваш инструмент, с использованием пошаговых примеров, которые гарантированно будут каждый раз работать точно так, как описано
• практические советы , раздел поваренной книги, куда пользователи могут перейти, чтобы ответить на вопросы формы «Как мне…?», содержащие только те сведения, которые им нужны для данного вопроса.
• ссылка на
• обсуждение , в котором вы объясняете, почему все работает именно так, предоставляете справочную информацию, советуете, какие методы лучше использовать, а какие - плохие, и иным образом даете контекст, который не подходит для других разделов.

Эта проблема устарела, потому что она открыта 365 дней без активности.

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