Типичные улучшения

Для поиска по тегу начните название тега с символа '@'.

Улучшения, показаны 18 из 18.

Вынесите вставки кода в отдельные блоки

В Markdown есть два формата для вставок кода. Первый — это inlines. Его применяют для …

Включите подсветку синтаксиса в блоках кода Markdown

Подсветка синтаксиса заметно облегчает чтение кода. Сразу становится видно где вызвана функция, где начинается цикл …

Раскройте продуктовую ценность программы

В описании работы программы крайне нежелательно оперировать терминами "переменная", "функция", "цикл" и так далее. Ещё …

Включите подсветку синтаксиса

Код на питоне удобнее читать, если в нём есть подсветка синтаксиса. Сравните: +++ Без подсветки …

Проиллюстрируйте то, о чём говорите

Некоторые вещи проще один раз показать, чем описывать словами. Сравните два описания: > Для работы …

Сделайте ссылки в документации кликабельными

Если ссылка в документе есть, но кликнуть по ней нельзя, то придется выделить и скопировать …

Разбейте одно предложение на несколько

Чем больше информации в документе, тем сложнее его понять. Бывает, что в документе всё на …

Замените список на абзацы текста

В тексте и список, и абзацы решают одну задачу - задают структуру текста, разбивая его …

Избавьтесь от знаков препинания в заголовках

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

Ответьте на дополнительные вопросы

При чтении работы возникли дополнительные вопросы, ответы на которые получить не удалось.

Перепроверьте утверждение

Некоторые из утверждений не верны.

Замените термины с программистских на продуктовые

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

Расскажите о пользе на примере ситуации

Спросите любого в чём польза от того или иного приспособления, и собеседник сразу начнёт вспоминать …

Не используйте заголовки для выделения текста

Заголовки -- это особый элемент форматирования текста. Он предназначен для выделения главной мысли в абзаце, …

Используйте терминологию Python

В Python нет "массивов", вместо них используют "списки". То же самое со словарями: это теперь …

Используйте заголовки для разделения текста

Заголовки -- это особый элемент форматирования текста. Он предназначен для выделения главной мысли в абзаце, …

Разбейте одно предложение на несколько

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

deprecated