Развитие русской справки
- Автор темы AZJIO
- Дата начала
По мне новичку лучше сразу привыкать к общепринятым понятиям :
Т.е: Опционально
Добавлено:
Не стоит стремиться перевести все слова.Так можно дойти до абсурда.
Если размер критичен,то можно даже : (Опц.)
Новичок все равно поймет, если не с первого раза, так со второго.
С первого раза ему даже применение параметра : Необязательный будет не очень понятно
Т.е: Опционально
Добавлено:
Сообщение автоматически объединено:
Не стоит стремиться перевести все слова.Так можно дойти до абсурда.
Если размер критичен,то можно даже : (Опц.)
Новичок все равно поймет, если не с первого раза, так со второго.
С первого раза ему даже применение параметра : Необязательный будет не очень понятно
1 Справка русская, и иностранные термины лучше переводить, если они имеют в русском языке достойные аналоги, "необязательный" в данном случае вполне понятный аналог.
Для примера возьмем описание InputBox. Строка синтаксиса этой команды:
3 Смотрим далее описание в таблице:
4 Как вариант можно заменить это слово, вместе с квадратными скобками, на звездочку и в Примечании написать:
5 У новичка больше вопросов может вызвать, как записать команду, если ему нужно указать один из "необязательных" параметров, а остальные, стоящие левее, "необязательные" параметры ему не нужны.
Возвращаясь к нашему примеру, ему нужно указать параметр timeout. Что нужно указать вместо пропущенных левее параметров !?
Где это объяснено?
Для примера возьмем описание InputBox. Строка синтаксиса этой команды:
2 Я новичок в AutoIt, но из чтения других справок знаю, что необязательные параметры в строке синтаксиса общепринято указывать в квадратных скобках. А если новичок этого не знает, то этот "штакетник" из квадратных скобок делает эту строку для него непонятной. Объяснения этих квадратных скобок я не встретил в справке. :(
3 Смотрим далее описание в таблице:
Выделенное жирным и расположенное в начале строки слово [опционально] отвлекает от описания и мешает его читать. Это слово нужно перенести в конец описания и убрать жирность (можно заменить ее на курсив)
4 Как вариант можно заменить это слово, вместе с квадратными скобками, на звездочку и в Примечании написать:
Это будет понятно и не будет занимать много места в таблице.
5 У новичка больше вопросов может вызвать, как записать команду, если ему нужно указать один из "необязательных" параметров, а остальные, стоящие левее, "необязательные" параметры ему не нужны.
Возвращаясь к нашему примеру, ему нужно указать параметр timeout. Что нужно указать вместо пропущенных левее параметров !?
Где это объяснено?gregaz
sngr
gora
Если новичку надо к чему то привыкать, то уж точно не к сокращениям и каким-то англо-словам, а к метке как я предлагал [?]. Это всего лишь символьная метка. Я не читаю слова, мне достаточно увидеть жирное пятно, которое я хотел уменьшить для удобства чтения. Так что если мы голосуем за символьную метку, так голосуем либо за мой вариант либо за вариант предложенный CreatoR'ом. Иначе голоса делятся либо на два варианта с одинаковым рейтингом, либо голоса за символьную метку распадаются на подварианты и проирывают.gregaz сказал(а):
Не переводя достойными заменами сделаем справку, которая создаёт больше вопросов, чем ответов.
sngr
Да, это слово моднее звучит, чем "необязательный", как например "тенденция, моветон, амплуа, апофеоз". Поэтому оно придаёт справке солидность в ущерб пониманию.
gora
Мы приватно обсуждали этот вопрос, но скажу здесь почему я не согласен. Конец каждой строки не имеет постоянной позиции и неудобно выискивать эту метку, в крайнем случае добавить колонку в конце таблицы, но опять же колонка займёт ширину в том числе и у обязательных параметров.
опять же выискивать звёздочку.
Да, у некоторых функций не указано что должен содержать параметр если его требуется игнорировать. UDF в этом плане намного проще, там параметры указаны сразу в синтаксической строке функции, или в любом случаем можно заглянуть в сам UDF. Думаю такие функции нужно отписывать здесь и на офсайте, чтобы документировать.
AZJIO [?]
AZJIO [?]
Я понимаю Вас как создателя скрипта по сборке справки, но сложности в написании такого скрипта не могут быть доминирующими над удобством чтения самой справки, которую будут читать тысячи пользователей и которым этот скрипт с его сложностью будет "до лампочки"
AZJIO [?]
А вот звездочку можно оставить и в начале описания параметра, она не так будет мозолить глаза. Вы же сами предлагали [?], вот и замените ее на *
sngr
gora
gora [?]
Была такая мысль, но будет явное отклонение от оригинала справки, так как эти утилиты не входят в установщик по умолчанию.
Сейчас всё возможно найти на вкладке "Указатель", введя даже часть слова. А на вкладке "Поиск" даже страницы где встречается слово.
gora
Вообще компилятор я получил от SyDr, я лишь его модернизировал, добавив Gui, некоторые подсветки по тексту.
в контексте я имел ввиду неудобство чтения, а не сложность скрипта.
gora [?]
Да, но звёздочка символ обязательного параметра. Кстати, вот и пример когда используется символьная метка без длинных текстов её описания.
AZJIO [?]
Пример Откройте на странице Executive Summaries -> Affected Software and Download Locations -> Windows Operating System and Components и увидите звездочки как символ примечания с объяснением этих звездочек в конце раздела.
Ну пусть не звездочка, а какой-то другой символ, например "•"
Откуда такая информация? Впервые слышу. :( Всегда считал звездочку в конце предложения символом примечания...
Пример Откройте на странице Executive Summaries -> Affected Software and Download Locations -> Windows Operating System and Components и увидите звездочки как символ примечания с объяснением этих звездочек в конце раздела.
Ну пусть не звездочка, а какой-то другой символ, например "•"
Опционально - буквальный перевод слова optional, коие есть стандарт для аглийской версии справки, так пишут на msdn - да везде это используется. Когда справка для версии 3.6.6.1 была только английской, я смотрел что делает неизвестная мне функция в руской справке для 3.2.5.4, а параметры в английской, в крайнем случае есть пример, понятный на любом языке. У новичков проблема не в понимании того, что написано, а в незнании где нужную информацию найти. Если ты хочешь сделать такую же, но с блек джеком и шлюхами - твоё право, но я бы предложил тогда на верхней крышке написать разноцветными весёлыми буквами Don`t panic и больше использовать ресунки, что бы и неумеющие читать всё поняли.
sngr
"DllClose is still a good idea" буквально переводится "DllClose всё же хорошая идея". У нас так не говорят, у нас "рекомендуется". Буквальный перевод был при первом переводе справки, теперь есть желание осмыслить.
ок, я пришёл к программированию на AutoIt минуя msdn. Поэтому "опция" ассоциируется с некоторым переключателем, в котором может находится параметр, а не как не игнорирование параметра.
я тоже могу чёнить написать, но не буду.
Не обижайся, с Don`t panic моя вольная цитата из одной хорошей книги.
Ты меня непривильно понял - я говорю о том, что optional можно вообще не переводить, тк это элемент оформления, как содержание, поиск и тд слева, заголовок сверху и тд. Привычный элемент. Ты как автор русской справки можешь сделать как тебе угодно - мы как пользователи привыкнем к любому виду, но лучше придерживаться общепринятых стандартов.
CreatoR
sngr
Можно ссылочку на msdn, где именно указано по русски "опционально(ый)". Я по запросу "программирование опциональные параметры" больше встретил словосочетание "необязательные параметры", так что сомнение что "опциональные" стало стандартом, а в некоторых справочниках просто не указано.
да, ещё лучше.
sngr
Можно ссылочку на msdn, где именно указано по русски "опционально(ый)". Я по запросу "программирование опциональные параметры" больше встретил словосочетание "необязательные параметры", так что сомнение что "опциональные" стало стандартом, а в некоторых справочниках просто не указано.
Предлагаю ещё раз проголосовать с учётом выше сказанного и с предпросмотром как это будет выглядеть:
[необязательный]
[опционально]
[?]
•
[необязательный] в конце
[необязательный]
[опционально]
[?]
•
[необязательный] в конце
- Сообщения
- 8,673
- Репутация
- 2,486
AZJIO [?]
Мне лично кажется что [необязательный] будет оптимальным решением.
Или, если так сильно нравится вариант с [?], то стоит задуматься над реализацией акронима, т.е чтобы при наведении на ссылку с этим вопросиком, появлялась подсказка с описанием, типа: «Данный параметр не обязательный, если параметр пропускается, то вместо значения используйте Default» (как то так
).
Голосование здесь не уместно, пользоваться будут сотни, а голосовать всего несколько.
Мне лично кажется что [необязательный] будет оптимальным решением.
Или, если так сильно нравится вариант с [?], то стоит задуматься над реализацией акронима, т.е чтобы при наведении на ссылку с этим вопросиком, появлялась подсказка с описанием, типа: «Данный параметр не обязательный, если параметр пропускается, то вместо значения используйте Default» (как то так
).CreatoR
gora
, поправил.
Я не хочу сделать хуже, или в пользу себе, поэтому я и хотел бы чтобы услышать продуманное мнение, а не потому что мы так привыкли и если поменяем вдруг будет хуже. Если будет 30% против символичной метки, думаю можно оставить ближе к оригиналу.
я уже добавил в примере выше всплывающую подсказку.
gora
для дискриминации
, поправил.добавил
Думаю если во всех одинаковый формат то лучше вынести это в описание к функции.
