Википедия:Оформление статей/Статьи об информационных технологиях
![]() | Эта страница является тематическим соглашением проекта «Информационные технологии». |
Эта страница предлагает обобщённые варианты оформления, собранные в рамках Проекта Информационные технологии, для статей об информационных технологиях и обо всём, что так или иначе с ними связано. Она не является правилом Википедии или руководством, описанное здесь — не догма. Руководствуйтесь ситуацией и здравым смыслом.
Разное
[править код]- Стоит осторожно относиться к замене текста/определений в статьях на текст из разных "регламентирующих" документов какой-то одной страны, например, гостов. Иногда такую информацию лучше просто добавить к тексту или в новый абзац, что способствует нейтральности и освещению разных существующих точек зрения. Можно сравнить документы страны и международные документы (напр. iso).
- Для улучшения статьи полезно смотреть на статусные статьи (хорошие, избранные... Категория:Статьи проекта Информационные технологии по уровню) и дискуссии через которые они избирались.
- про буфер: темы в проекте Грамотность (2015), оспаривание итогов (2015), /Буфер и сервер, Проект:Грамотность/Вопросы лингвистам#Буферы/буфера, Обсуждение проекта:Грамотность/Вопросы лингвистам#Буферы/буфера
- про другие слова: директория /Каталог, /Pixel, /Framework
- Не стоит бояться способов иллюстрирования. Прямо в тексте статьи можно размещать не только текст, но и сложный код. Нет железного требования на качество иллюстрации - загрузить фото рисунка/схемы от руки - почему бы и нет, можно даже попросить перерисовать в ПРО:ЗАГРАФ. Графики Википедия:Иллюстрирование#Графики выглядят сложными? - соберите нужное html'ными div'ами или тегом pre прямо в тексте, потом кто-нибудь дооформит.
- Оформление единиц измерений wikisource:ru:Индекс:Resolution of the Government of the Russian Federation №879 2009-10-31.pdf (ГОСТы сильнее общих словарей. Постановление правительства в общем случае сильнее ГОСТа. ГОСТ - нормативный документ и в нём могут появляться новые дополнения. Это постановление 2009 года может появится новое постановление или поправки. ГОСТы оформленные простым текстом даже на официальных сайтах содержат ошибки оформления и могут быть невыверенными версиями. В спорных случаях лучше ориентироваться на официальные печатные постановления и фиксированные pdf с официальных сайтов, чем на текстовые версии, но даже в pdf может оказаться H2O вместо H2O). ГОСТ 8.417—2002. Государственная система обеспечения единства измерений. Единицы величин. Положение о единицах величин, допускаемых к применению в Российской Федерации . Федеральный информационный фонд по обеспечению единства измерений. Росстандарт. Дата обращения: 21 мая 2017.
Оформление листингов в статьях об алгоритмах
[править код](Черновик предложения о порядке переноса излишних листингов)
Описываемые в Википедии алгоритмы как правило имеют описание на псевдокоде. Преимуществом этого подхода является независимость от среды исполнения и контролируемая степень формальности, позволяющая описывать суть алгоритма, данного в авторитетном источнике, не отвлекаясь на детали.
Как правило, в статье не должно быть листингов на реальных языках программирования, за исключением случаев, когда:
- в статье нет описания на псевдокоде
- псевдокод требует бо́льшего объёма пояснений, чем краткий код на языке программирования. Данный пункт применим только для случаев, когда язык листинга имеет признанную, известную семантику и широко употребляется в авторитетных источниках для иллюстрации данного алгоритма (например, если алгоритм использует битовые операции на Си, определения функций на ML, матричные операции в Matlab, Octave, R, scipy)
- код достаточно краток и является распространённой цитатой, применяемой в АИ (не считая оригинала)
В случае необходимости проиллюстрировать алгоритм (прежде чем вставлять код на каком-либо языке) рекомендуется просмотреть интервики на наличие подходящих иллюстраций и псевдокода. Предпочтительнее скопировать и вставить псевдокод (например из en, de -вики). Раздел со скопированным псевдокодом, но без перевода сопровождающего описания, нужно дополнить шаблоном Ш:Закончить перевод. В описании правки, добавляющей скопированный псевдокод, необходимо указывать ссылку на статью из которого он взят (для соблюдения лицензии). Не допускается использование реализаций более чем на двух языках программирования при иллюстрации одного и того же момента.
В каждом конкретном случае, в том числе в случае длинного листинга, следует рассматривать его энциклопедическую ценность для статьи, органичную включённость в изложение и проверяемость. Если целесообразность в статье об алгоритме листингов вызывает сомнения, рекомендуется перенести листинги на всех языках программирования в Викиучебник Реализации алгоритмов, организованный по аналогии с Кулинарной книгой.
- Википедия:Чем не является Википедия#Википедия — не сервер-зеркало, не файловый архив и не каталог ссылок "Статьи Википедии не должны представлять собой подборки исходных материалов таких как исходные коды"
- Википедия:Чем не является Википедия#Не инструкция "Статьи не должны выглядеть как инструкции или указания, или содержать пошаговые инструкции (в стиле «как сделать»), включая пошаговые обучающие руководства, схемы прохождения, инструкции по эксплуатации и рецепты"
Примеры кода
[править код](основа: en:Wikipedia:WikiProject Computer science/Manual of style)
Примеры реального исходного кода приводятся в статьях по различным причинам, чаще всего для иллюстрации подхода конкретного языка, для приведения примеров специфичных для языка конструкций или особенностей, и в качестве примера для алгоритма, который нелегко выразить на псевдокоде. Хотя во включении в статью примера кода нет ничего плохого, чрезмерное его количество может отвлечь внимание от содержимого самой статьи. Поэтому следует избегать написания любого примера, если он не внесёт значимого вклада в фундаментальное понимание энциклопедического содержимого.
Википедия не является репозиторием исходного кода. Код, не относящийся к энциклопедическому содержимому, должен быть перемещён за пределы Википедии. Викиучебник - подходящий проект Викимедиа для кода с GFDL-совместимой лицензией, в частности, учебник b:Реализации алгоритмов.
Внешние вики LiteratePrograms и Rosetta Code — это подходящее место для размещения "новых" примеров реализаций вместе с описанием того, как эти реализации работают. Важное примечание: существующие в Википедии реализации не могут быть перенесены в вики LiteratePrograms, потому что содержимое Википедии лицензировано на условиях GFDL, а LiteratePrograms использует GFDL-несовместимую лицензию MIT/X11.
Некоторые основные рекомендации по примерам кода:
Несмотря на возможное наличие реализации на некотором языке программирования, каждая статья об алгоритме должна содержать, если это возможно, описание алгоритма на псевдокоде, чтобы всякий мог понять, как он работает. См. рекомендации касающиеся псевдокода.
- В примере нужно использовать язык, который ясно проиллюстрирует алгоритм читателю, не знакомому с языком, даже если вы уверены, что язык известен всем. Чтобы сохранить нейтральность в использовании языков, рекомендуется выбирать языки по принципу лучшей ясности (читабельности), а не популярности. Например, языки, обладающие хорошей читабельностью, такие как Python или Ruby, являются хорошим выбором. В листингах избегайте эзотерических (т. е. известных лишь немногим) и специфичных для отдельного языка конструкций.
- Реализации исходного кода должны быть совместимы с лицензиями GFDL и CC-BY-SA (эти лицензии несовместимы с GPL).
- Множественные реализации в исходном коде не являются допустимыми, если они не ставят целью противопоставить конкретные аспекты кода или если это противопоставление не является важным для энциклопедического содержимого статьи. Если возможно, для подчёркивания различий следует использовать альтернативную реализацию на том же языке.
- Все примеры кода должны быть оформлены с использованием одного из следующих методов:
- заключить короткий, внутристрочный пример кода в тег
<code>
- заключить блок кода в теги
<pre>
или<syntaxhighlight lang="x">
- выделить блок кода одним или более пробельным отступом в начале строк (в отличие от предыдущего метода, этот позволяет использовать базовое форматирование текста, такое как полужирное начертание и т. д. в примере)
- заключить короткий, внутристрочный пример кода в тег
Таким образом, они будут набраны моноширинным шрифтом, чтобы убедиться, что расстояние сохраняется и обеспечивает дополнительную информацию экранным дикторам и пользователям с изменённым CSS. Это особенно важно делать для тех языков, где пробелы имеют синтаксическое значение — в идеале мы хотели бы, чтобы люди могли копировать и вставлять пример кода в текстовый редактор или IDE (без видимых искажений). Например,
int main(void) { printf("hello, world\n"); return 0; }
- Подсветить синтаксис можно используя тег
<syntaxhighlight lang="x">
вместо<pre>
, где x это используемый язык. См. поддерживаемые языки в Extension:SyntaxHighlight. Например, так подсветится синтаксис кода на Java:
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello World!"); // Print "Hello World!"
}
}
- Так как в листингах кода не переносятся слова, и многие люди читают Википедию на устройствах с ограниченным экранным пространством, убедитесь, что в листинге кода максимальная длина строки не превышает 60 символов. Переносите слова вручную, если потребуется.
Как перенести текст в Викиучебник
[править код]1. Ориентируясь по категориям на главной странице Викиучебника, определить в какую из книг нужно перенести текст.
- 1.1 Создать отсутствующую книгу или раздел существующей книги.
- В выбранную книгу добавить подстраницу по аналогии с другими, обычно в виде:
[[книга/Алгоритм X|Алгоритм X]]
. (TODO: дать инструкции в обсуждении викиучебника?) - Дать ссылку на статью в Википедии в начале страницы
{{wikipedia|Алгоритм Коэна — Сазерленда}}
- Проставить категорию
{{BookCat}}
- По возможности поставить интервики.
- В выбранную книгу добавить подстраницу по аналогии с другими, обычно в виде:
2. Копирование текста из Википедии в Викиучебник.
- 2.1. При создании страницы в Викиучебнике, для соблюдения авторской атрибуции в описании правки нужно привести ссылку на статью, из которой был заимствован текст
Перенесено из [[:w:ru:Статья]]
(пример получающегося описания правки: Перенесено из w:ru:Perl).
- 2.2. Скопировать вики-текст с листингами кода, исправив при необходимости уровни заголовков.
- 2.3. Добавить словесное описание алгоритма. Можно скопировать часть преамбулы, добавив префикс
w:
к внутренним ссылкам Википедии.
3. Удалить код листингов из статьи в Википедии, указав в описании правки Перенесено в [[b:Реализации алгоритмов/Алгоритм X]]
4. Добавить ссылку на статью Викиучебника в статье Википедии:
- 4а. поставив шаблон
{{Викиучебник|Реализации алгоритмов/Алгоритм X|Примеры реализации алгоритма X}}
- 4б. или текст
''См. также [[b:Реализации алгоритмов/Алгоритм X|Примеры реализации алгоритма X]]''
- 4в. Альтернативно (и по ситуации), в разделе Ссылки можно поставить шаблон:Навигация:
{{Навигация |Тема = Темастатьи |Портал = |Викисловарь = темастатьи |Викиучебник = Реализация алгоритмов/Алгоритм X |Викицитатник = |Викитека = |Викивиды = |Викиновости = |Викисклад = |Метавики = |Проект = }}
Примечания:
- когда страница Википедии удаляется, с материалом необходимо перенести полную историю изменений исходной страницы, что может сделать администратор по явному запросу на b:Викиучебник:Запросы к администраторам.
- в случае если текст заимствуется не из версии статьи Википедии, последней на момент времени сохранения в Викиучебнике (так, что по временной метке версии Викиучебника последняя версия до этой временной отметки статьи Википедии не содержит такого текста) удобно привести ссылку на ту постоянную версию, из которой был заимствован текст или в которой он был добавлен в статью (боковое меню - инструменты - Постоянная ссылка)
- (пример:
Перенесено из [[:w:ru:Статья]] [[:w:ru:Special:PermanentLink/624960278]]
, будет Перенесено из w:ru:Статья w:ru:Special:PermanentLink/624960278) - или ссылку на правку, которой текст был удалён из статьи (из истории правок)
- (пример:
Перенесено из [[:w:ru:Статья]] [[:w:ru:Special:Diff/67563661]]
, будет Перенесено из w:ru:Статья w:ru:Special:Diff/67563661).
- На странице обсуждения статьи в Викиучебнике по желанию можно дать ссылку на diff и/или версию статьи в Википедии в свободной форме, используя w:en:Help:Wiki markup#Linking to old revisions of pages, diffs, and specific history pages. Подобно шаблону Ш:Переведённая статья.
Приветствуется дальнейшее улучшение статей в Викиучебнике для повышения его образовательной ценности.
Рекомендации и замечания
[править код]Не рекомендуется добавлять большой листинг в текст статьи. Можно указать в конце статьи (в разделе Ссылки) шаблоном Ш:Викиучебник ссылку на такой листинг в Викиучебнике, разместив и достаточно прокомментировав листинг там. Чтобы не накапливать в статье ссылки на внешние сайты, их тоже в основном можно дать в виде ссылок в конце страницы в Викиучебнике. Пример: Алгоритм Коэна — Сазерленда → b:Реализации алгоритмов/Алгоритм Коэна — Сазерленда. Можно давать ссылки и на статьи Викиучебника на других языках (например, из англ. b:en:Category:Computing).
Не рекомендуется помещать листинг в шаблоны вида Википедия:Сворачивающиеся блоки. Такие шаблоны: не показываются: на печати, в pdf, в мобильной версии; очень неудобно править в визуальном редакторе (как гигантское содержание шаблона).
Перед листингом рекомендуется размещать викиссылку на статью, разъясняющую используемые в листинге нетривиальные конструкции языка.
Теги:
- внутристрочный html-тег
<code></code>
[1], (<code style="border:1px solid #444444; padding:2px">) - html-тег
<pre></pre>
[2];<poem style=""></poem>
mw:Extension:Poem - Код подсвечивается с помощью расширения mw:Extension:SyntaxHighlight, которое добавляет тег
<syntaxhighlight lang=""></syntaxhighlight>
. mw:Extension:SyntaxHighlight/ru (см. также историю страницы), mw:Extension:SyntaxHighlight (Показываемый список языков неполный. Под списком даётся ссылка на все доступные языки, откуда нужно взять Short names для подходящего случая. Например, python console session - pycon)- Extension:SyntaxHighlight раньше работало со старым тегом
<source lang=""></source>
, сейчас он альтернативный дополнительный. Новый тег syntaxhighlight введён из-за случаев когда в подсвечиваемом коде (например, XML) содержится тег<source>
, который нужно подсветить, а не обработать. Все страницы с тегом source попадают в Category:Страницы, использующие устаревший тег source поэтому лучше вместо него использовать syntaxhighlight.
- Extension:SyntaxHighlight раньше работало со старым тегом
Параметры:
- lang
<syntaxhighlight lang="">
название языка; - line
<syntaxhighlight lang="" line>
или<syntaxhighlight lang="" line="GESHI_NORMAL_LINE_NUMBERS">
показывает обычную нумерацию строк;<syntaxhighlight lang="" line="GESHI_FANCY_LINE_NUMBERS">
показывает нумерацию строк в которой каждая пятая цифра выделена жирным;
- start
<syntaxhighlight lang="" line start="n">
изменяет нумерацию (line включает нумерацию) строк начиная её с указанного числа n; - highlight
<syntaxhighlight lang="" highlight="n">
"1,4,8" "5-7" "1,5-7"
подсвечивает строку. Не учитывает изменение видимой нумерации параметром start. Строки можно перечислить через запятую. <syntaxhighlight lang="" enclose="div">
Заключает код в div. Длинная строка автоматически переносится. При использовании месте с line - каждая строка оформляется в div.<syntaxhighlight lang="" enclose="pre">
(по умолчанию) Заключает код в pre. При использовании месте с line - каждая строка оформляется в pre. У длинных строк появятся полосы прокрутки.- inline делает внутристрочным. Для обратной совместимости атрибут
enclose="none"
приводит к такому же поведению.- если установлено значение «none», его следует заменить на inline; в противном случае его можно полностью удалить.<syntaxhighlight lang="" enclose="none">
оформляется в div со светлым фоном- Category:Страницы с устаревшим атрибутом подсветки синтаксиса «enclose»
- strict в некоторых случаях исправляет подсветку
- class
- style
- mw:Extension:SyntaxHighlight/ru#Параметры
- lang
todo: пример псевдокода как образцовый
todo: про схемы, в чем, как, цвета,
i++
Степень комментирования должны быть адекватной сложности алгоритма для восприятия с учётом того, что читатель уже ознакомился с самим алгоритмом по викистатье. В отличие от "производственного" программного кода, в листингах допускается комментировать использованные языковые конструкции, так как считается, что читатель может быть новичком в программировании.
В истории правок могут быть примеры реализаций, удалённые как неформат, ВП:ЧНЯВ и т. п. (например, как случилось в статье мультиметод). Если удаление не было связано с плохим качеством материала, такие листинги тоже можно перенести в Викиучебник.
В статьи с включениями кода рекомендуется добавлять категории из Категория:Статьи с примерами кода.
Небольшой листинг - листинг до 15 строк кода (не считая отступов и комментариев) в отдельном блоке кода.
"В целом, с точки зрения АП компьютерные программы охраняются в первую очередь, именно как текстовые произведения, и во вторую получают доп. охрану. Поэтому, если бы берёте чужой код - вы должны на него как минимум сослаться и обозначить автора. Другой вопрос - зачем использовать чужой (несвободный) код, если можно написать свой." (Википедия:Форум/Авторское_право#Листинги кода из книжки)
Структура статей о языках программирования
[править код]-история название/этимология философия/цели/характеристики/отличия стандартизация/лицензии/торговые марки история/версии -язык синтаксис/элементы(типы данных/функции/объекты) парадигмы/программирование/возможности -библиотеки/реализация парсинг/обработка/компиляция/использование -инструменты/среды/сообщества -критика/оценка/сравнения (аи...) *примеры не должны быть представлены галереей в конце статьи, их нужно использовать в разделах статьи
Книги (см. раздел "Похожие книги")
Иноязычные термины
[править код]Когда у термина несколько переводов лучше использовать «тот что используется в преобладающем большинстве АИ», «тот что используется в научных работах признанных специалистов в данной теме».
Если к переводу не находится достойных документальных подтверждений, не стоит указывать его в первом определяющем предложении/преамбуле, но можно написать о нём позднее в тексте. В Википедии нужно опасаться утверждений или ввода новых слов или старых к новым понятиям, так «слово (с англ. — „словище“)» выглядит для читателя как утверждение что А это Б (в первом, то есть определяющем предложении это будет вводить в заблуждение или вызывать недоверие ко всей статье). В тексте отдельным предложением переводы могут быть упомянуты например так «На русском слово Х» «буквально, может быть переведено, обычно переводится, значит», [3].
Когда достойных источников с переводами мало, в тексте статьи можно использовать оригинал, а нераспространённый вариант(ы) перевода указывать только в предложении о его существовании. Например, если издана только одна книга или пара книг от одного издательства/автора, можно написать «В источнике А был использован перевод А1. В источнике Б был использован перевод Б1».
Оформление начала
[править код]- Вместо текста "по русски произносится" или "произносится как" лучше дать фонетическую транскрипцию в шаблоне IPA.
- Запись слов текстом на русском по практической транскрипции Википедия:Транскрипция.
- Ссылки для подхода к выботу оформления: Википедия:Именование статей, Википедия:Именование статей/Иноязычные названия, en:Wikipedia:Article titles, en:Wikipedia:Naming conventions (use English), Википедия:Произношение, en:Wikipedia:Manual of Style/Pronunciation, Википедия:Преамбула, en:Wikipedia:Manual of Style/Lead section, en:Template:Nihongo, en:Help:Pronunciation respelling key, оформление избранных статей Википедия:Избранные статьи en:Wikipedia:Featured articles
Связанные правила
[править код]- Википедия:Критерии значимости веб-сайтов
- Википедия:Критерии значимости программ
- Википедия:Критерии значимости персоналий#Программисты
- en:Wikipedia:Software screenshots
- en:Wikipedia:WikiProject Computer science/Manual of style
- en:Wikipedia:Manual of Style/Computing
- en:Wikipedia:Notability (software)
- en:Wikipedia:Notability (organizations and companies)
- en:Wikipedia:Scientific citation guidelines
- en:Wikipedia:Stand-alone lists
Обсуждения
[править код]- Википедия:Форум/Архив/Предложения/2008/10#Критика закрытого исходного кода в статьях о программном обеспечении
- Википедия:Форум/Архив/Вниманию участников/2010/11#Метод Лемана
- Википедия:Форум/Архив/Изображения/Январь 2007#Лицензии для скриншотов бесплатных программ
- Википедия:Форум/Архив/Авторское право/2014/04#Файл:MirandaNG Logo.png
- Википедия:Форум/Трудности перевода/Архив/2#Firmware
- Википедия:Форум/Архив/Авторское право/2012/06#Высший Европейский суд признал незаконным запрет обратного инжиниринга
- Википедия:Форум патрулирующих/Архив/2010/11#Пример с подписью
- Википедия:Форум патрулирующих/Обсуждение статей/Архив/2010/1#Просьба отпатрулировать 3
- Википедия:Форум/Правила#О программистах
- обсуждения проектов, статусных статей и их рецензии
Источники информации по темам
[править код]См. также
[править код]- mw:Manual:RFC
- Википедия:Статьи о программах и утилитах (эссе)
- Википедия:Критерии значимости программ (действующее правило)
- Википедия:Критерии значимости персоналий#Программисты (действующее правило)
- Википедия:Статьи о компьютерных играх (проект правила)
- Википедия:Оформление статей
- Википедия:Страница-шаблон
- Проект:Информационные технологии/Мёртвые ссылки
- Проект:Информационные технологии/Минимальные требования к статьям о мобильных устройствах