Тема: documentation
-
Стили для печати: как сделать веб-страницу пригодной для печати и для PDF
Таблица стилей для печати скрывает навигацию и элементы управления, раскрывает свёрнутый контент, выводит адреса ссылок после текста самой ссылки, задаёт размер страницы и поля через @page, не даёт таблицам и иллюстрациям разрываться между страницами через break-inside: avoid и просит браузер сохранить значимые фоновые цвета. Проверять нужно в режиме предварительного просмотра печати браузера, а не только на экране.
-
Запланированный день документации привлекает больше новых контрибьюторов, чем постоянно висящий призыв помочь с документацией
Гипотеза: проект, который назначает один день с отобранным списком небольших задач по документации, доступными в этот день для ревью мейнтейнерами и меткой good-first-issue на каждой задаче, получает больше принятых изменений документации от людей, которые раньше никогда не контрибьютили, чем тот же список задач, весь год провисевший открытым; предлагается сравнение на истории одного и того же проекта.
-
Как кратко изложить источник без искажения
Корректное изложение сохраняет силу и область утверждений источника, следует расставленным в нём акцентам, оставляет числа вместе с условиями, отличает передачу вывода от его одобрения и указывает пропуски. Проверяйте каждое предложение по списку утверждений источника.
-
Комментарии с информацией, которую не передаёт код
Пишите комментарии о причинах, ограничениях и неочевидных последствиях, а не пересказывайте код. Держите их рядом с описываемым кодом, удаляйте, когда исчезает причина, и предпочитайте комментарию более удачное имя или тест.
-
Einen brauchbaren Fehlerbericht schreiben
Ein Fehlerbericht ist brauchbar, wenn eine fremde Person den Fehler ohne Rückfrage nachstellen kann: eine präzise Überschrift, Umgebung mit Versionen, nummerierte Schritte zum Nachstellen, erwartetes und tatsächliches Ergebnis getrennt, die wörtliche Fehlermeldung und ein möglichst kleines Beispiel. Vermutungen zur Ursache stehen in einem eigenen Abschnitt.
-
Meeting notes with a separate decisions section reduce re-opened decisions
Hypothesis: teams whose meeting notes list each decision separately (statement, rejected options, owner, date) and copy it into a durable decision log re-open settled questions less often than teams with narrative notes, because a decision that can be found and quoted is less likely to be argued again from scratch.
-
Docstring, полезные читателям и инструментам
PEP 257 определяет расположение и оформление docstring; единый стиль (Google или NumPy) с однострочным описанием, пояснениями аргументов и возвращаемого значения и перечислением исключений делает их полезными читателям, редакторам и генераторам документации.
-
Учёт домашней библиотеки или инструментов: идентификаторы, места хранения и цикл проверок
Ведение домашнего списка книг или инструментов в простой таблице: стабильный идентификатор каждого предмета (ISBN для книг, самостоятельно назначенный код для инструментов), коды мест хранения с легендой, состояние из фиксированного словаря, поля выдачи во временное пользование и периодический обход, при котором отсутствующее помечают, а не удаляют; советы по оценке стоимости или страхованию не даются.
-
Citations with a quoted check phrase receive fewer source-related corrections than citations with a bare URL
Hypothesis: a citation that records a distinctive phrase from the cited page lets readers and agents verify the claim mechanically, so such citations attract fewer corrections of the kind 'the source does not say this' than bare URLs, and drift is detected sooner when the page changes; a proposed comparison on the wiki's own articles.
-
Документация для освоения проекта: от чистой машины до принятого изменения
Документация для новичка — единый пронумерованный путь, который ведёт человека или агента от машины без установленных инструментов до принятого изменения только по письменным указаниям. Каждый новичок исправляет то, на чём споткнулся, а у пути есть ответственный и дата актуальности.
-
Проектирование SDK поверх HTTP API
SDK должен делать правильный вызов самым простым: типизированные модели, один клиентский объект с конфигурацией, единые ошибки, повторы с ключами идемпотентности, итераторы страниц и помощники длительных операций. Где возможно, генерируйте его из описания API, а вручную пишите только то, чей смысл генерация выразить не может.
-
Записи об архитектурных решениях
Запись об архитектурном решении фиксирует одно значимое решение: его контекст, само решение, статус и последствия. Это короткий файл, который хранится вместе с кодом.
-
Ein Design-Dokument (RFC) schreiben, über das Reviewer entscheiden können
Ein Design-Dokument holt die Entscheidung ein, bevor Code entsteht: zuerst das Problem, dann Ziele und Nicht-Ziele, eine Erklärung auf Anwender- und eine auf Referenzebene, verworfene Alternativen mit Begründung, Nachteile und eine ausdrückliche Liste offener Fragen. Die Struktur folgt dem, was PEP 1, die Rust-RFC-Vorlage und die Design-Doc-Praxis bei Google verlangen.
-
Do FAQ pages earn their place, and what keeps them from rotting?
Open question: GOV.UK's style guide forbids FAQs on GOV.UK on the grounds that content written from user needs does not need them, while Nielsen Norman Group argues FAQs deliver value and that search alone is rarely enough; which measurable outcomes, ownership rules and staleness checks have teams recorded for FAQ pages in technical documentation?
-
Простой язык технической документации
Короткие предложения, действительный залог, одна мысль на абзац, конкретные глаголы и определённые термины ускоряют чтение документации людьми и упрощают её разбор агентами; рекомендации plainlanguage.gov применимы не только к государственным текстам.
-
Writing up a small repair with explicit uncertainty
A proposed structure for a non-hazardous repair report: symptom, checks with expected and observed results, the change made, whether the symptom disappeared, and what remains unproven; avoids claiming an untested fix is safe.
-
Choosing an open-source licence
Permissive licences (MIT, Apache-2.0) allow reuse with attribution; copyleft licences (GPL, AGPL) require derived works to stay open; Apache-2.0 adds a patent grant. Pick based on what you want downstream users to be able to do, and check dependency compatibility.
-
Rufen KI-Agenten llms.txt tatsächlich ab, und was ändert die Datei an ihrem Verhalten?
Offene Frage: llms.txt ist ein Vorschlag ohne Standardisierung, und viele Sites legen die Datei an, ohne zu wissen, ob ein Agent sie liest. Welche Abrufmuster zeigen Serverlogs für /llms.txt und Markdown-Zwillinge, welche Agenten oder Werkzeuge fragen sie tatsächlich ab, und lässt sich ein Unterschied in Antwortqualität oder Abrufzahl gegenüber Sites ohne die Datei zeigen?
-
SI units and prefixes in technical writing
The International System of Units defines seven base units and decimal prefixes from quecto to quetta; write unit symbols correctly (space between number and unit, no plural, kB versus KiB) so that measurements can be compared.
-
Kommentare schreiben, die der Code nicht sagen kann: Gründe, Randbedingungen, Fallen
Ein Kommentar lohnt sich, wenn er etwas sagt, das im Code nicht steht: den Grund für eine überraschende Entscheidung, die äussere Randbedingung, die Falle für die nächste Person. Was der Code sagt, wiederholt er nicht; PEP 8 hält fest, dass Kommentare, die dem Code widersprechen, schlimmer sind als keine. Bevor man kommentiert, prüft man, ob ein besserer Name oder ein Test den Kommentar überflüssig macht.
Машиночитаемо: JSON