Что нового

Развитие русской справки

inververs

AutoIT Гуру
Сообщения
2,135
Репутация
465
Если справка для новичков, то и пишите "Этот параметр указывать не обязательно" :smile:
 
Автор
A

AZJIO

Меценат
Меценат
Сообщения
2,874
Репутация
1,194
inververs
:smile:

Kaster
ок

CreatoR
Я не хочу, чтобы меня критиковали за навязанный мною вариант [необязательный], который мне самому не нравится. Скажите что поставить и сделаю.
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
[Необязательный] однозначно.
 

gregaz

AutoIT Гуру
Сообщения
1,166
Репутация
299
По мне новичку лучше сразу привыкать к общепринятым понятиям :

Т.е: Опционально


Добавлено:
Сообщение автоматически объединено:

Не стоит стремиться перевести все слова.Так можно дойти до абсурда.

Если размер критичен,то можно даже : (Опц.)
Новичок все равно поймет, если не с первого раза, так со второго.
С первого раза ему даже применение параметра : Необязательный будет не очень понятно
 

sngr

AutoIT Гуру
Сообщения
1,010
Репутация
408
+ за опционально.
AZJIO Возможно имеет смысл перенести темы с AutoIt3Wrapper, Obfuscator и Tidy в раздел Использование AutoIt, а то если не знать где они находяться, найти совершенно невозможно.
 

gora

Знающий
Сообщения
315
Репутация
19
1 Справка русская, и иностранные термины лучше переводить, если они имеют в русском языке достойные аналоги, "необязательный" в данном случае вполне понятный аналог.
Для примера возьмем описание InputBox. Строка синтаксиса этой команды:
InputBox ( "title", "prompt" [, "default" [, "password char" [, width [, height [, left [, top [, timeout [, hwnd]]]]]]]] )
2 Я новичок в AutoIt, но из чтения других справок знаю, что необязательные параметры в строке синтаксиса общепринято указывать в квадратных скобках. А если новичок этого не знает, то этот "штакетник" из квадратных скобок делает эту строку для него непонятной. Объяснения этих квадратных скобок я не встретил в справке. :(
3 Смотрим далее описание в таблице:
width [опционально] ширина окна.

height [опционально] высота окна.
Выделенное жирным и расположенное в начале строки слово [опционально] отвлекает от описания и мешает его читать. Это слово нужно перенести в конец описания и убрать жирность (можно заменить ее на курсив)
4 Как вариант можно заменить это слово, вместе с квадратными скобками, на звездочку и в Примечании написать:
* Параметры, указанные в строке синтаксиса команды в квадратных скобках, является необязательными и могут отсутствовать в строке команды.
Это будет понятно и не будет занимать много места в таблице.
5 У новичка больше вопросов может вызвать, как записать команду, если ему нужно указать один из "необязательных" параметров, а остальные, стоящие левее, "необязательные" параметры ему не нужны.
Возвращаясь к нашему примеру, ему нужно указать параметр timeout. Что нужно указать вместо пропущенных левее параметров !? :shok: Где это объяснено?
 
Автор
A

AZJIO

Меценат
Меценат
Сообщения
2,874
Репутация
1,194
gregaz
gregaz сказал(а):
По мне новичку лучше сразу привыкать к общепринятым понятиям :
Если новичку надо к чему то привыкать, то уж точно не к сокращениям и каким-то англо-словам, а к метке как я предлагал [?]. Это всего лишь символьная метка. Я не читаю слова, мне достаточно увидеть жирное пятно, которое я хотел уменьшить для удобства чтения. Так что если мы голосуем за символьную метку, так голосуем либо за мой вариант либо за вариант предложенный CreatoR'ом. Иначе голоса делятся либо на два варианта с одинаковым рейтингом, либо голоса за символьную метку распадаются на подварианты и проирывают.

Не стоит стремиться перевести все слова.Так можно дойти до абсурда.
Не переводя достойными заменами сделаем справку, которая создаёт больше вопросов, чем ответов.

sngr
+ за опционально.
Да, это слово моднее звучит, чем "необязательный", как например "тенденция, моветон, амплуа, апофеоз". Поэтому оно придаёт справке солидность в ущерб пониманию.

gora
Это слово нужно перенести в конец описания и убрать жирность (можно заменить ее на курсив)
Мы приватно обсуждали этот вопрос, но скажу здесь почему я не согласен. Конец каждой строки не имеет постоянной позиции и неудобно выискивать эту метку, в крайнем случае добавить колонку в конце таблицы, но опять же колонка займёт ширину в том числе и у обязательных параметров.
4 Как вариант можно заменить это слово, вместе с квадратными скобками, на звездочку и в Примечании написать:
опять же выискивать звёздочку.
5 У новичка больше вопросов может вызвать, как записать команду, если ему нужно указать один из "необязательных" параметров, а остальные, стоящие левее, "необязательные" параметры ему не нужны.
Да, у некоторых функций не указано что должен содержать параметр если его требуется игнорировать. UDF в этом плане намного проще, там параметры указаны сразу в синтаксической строке функции, или в любом случаем можно заглянуть в сам UDF. Думаю такие функции нужно отписывать здесь и на офсайте, чтобы документировать.
 

gora

Знающий
Сообщения
315
Репутация
19
AZJIO [?]
Конец каждой строки не имеет постоянной позиции и неудобно выискивать эту метку
Я понимаю Вас как создателя скрипта по сборке справки, но сложности в написании такого скрипта не могут быть доминирующими над удобством чтения самой справки, которую будут читать тысячи пользователей и которым этот скрипт с его сложностью будет "до лампочки"
AZJIO [?]
опять же выискивать звёздочку.
А вот звездочку можно оставить и в начале описания параметра, она не так будет мозолить глаза. Вы же сами предлагали [?], вот и замените ее на *
 
Автор
A

AZJIO

Меценат
Меценат
Сообщения
2,874
Репутация
1,194
sngr
Возможно имеет смысл перенести темы с AutoIt3Wrapper, Obfuscator и Tidy в раздел Использование AutoIt
Была такая мысль, но будет явное отклонение от оригинала справки, так как эти утилиты не входят в установщик по умолчанию.
, а то если не знать где они находяться, найти совершенно невозможно.
Сейчас всё возможно найти на вкладке "Указатель", введя даже часть слова. А на вкладке "Поиск" даже страницы где встречается слово.

gora
Я понимаю Вас как создателя скрипта по сборке справки
Вообще компилятор я получил от SyDr, я лишь его модернизировал, добавив Gui, некоторые подсветки по тексту.
но сложности в написании такого скрипта не могут быть доминирующими над удобством
в контексте я имел ввиду неудобство чтения, а не сложность скрипта.
gora [?]
А вот звездочку можно оставить и в начало описания параметра, она не так будет мозолить глаза. Вы же сами предлагали [?], вот и замените ее на *
Да, но звёздочка символ обязательного параметра. Кстати, вот и пример когда используется символьная метка без длинных текстов её описания.
 

gora

Знающий
Сообщения
315
Репутация
19
AZJIO [?]
звёздочка символ обязательного параметра.
Откуда такая информация? Впервые слышу. :( Всегда считал звездочку в конце предложения символом примечания...
Пример Откройте на странице Executive Summaries -> Affected Software and Download Locations -> Windows Operating System and Components и увидите звездочки как символ примечания с объяснением этих звездочек в конце раздела.
Ну пусть не звездочка, а какой-то другой символ, например ""
 

sngr

AutoIT Гуру
Сообщения
1,010
Репутация
408
Опционально - буквальный перевод слова optional, коие есть стандарт для аглийской версии справки, так пишут на msdn - да везде это используется. Когда справка для версии 3.6.6.1 была только английской, я смотрел что делает неизвестная мне функция в руской справке для 3.2.5.4, а параметры в английской, в крайнем случае есть пример, понятный на любом языке. У новичков проблема не в понимании того, что написано, а в незнании где нужную информацию найти. Если ты хочешь сделать такую же, но с блек джеком и шлюхами - твоё право, но я бы предложил тогда на верхней крышке написать разноцветными весёлыми буквами Don`t panic и больше использовать ресунки, что бы и неумеющие читать всё поняли.
 
Автор
A

AZJIO

Меценат
Меценат
Сообщения
2,874
Репутация
1,194
sngr
Опционально - буквальный перевод слова optional
"DllClose is still a good idea" буквально переводится "DllClose всё же хорошая идея". У нас так не говорят, у нас "рекомендуется". Буквальный перевод был при первом переводе справки, теперь есть желание осмыслить.

так пишут на msdn - да везде это используется
ок, я пришёл к программированию на AutoIt минуя msdn. Поэтому "опция" ассоциируется с некоторым переключателем, в котором может находится параметр, а не как не игнорирование параметра.

Если ты хочешь сделать такую же, но с блек джеком и шлюхами - твоё право, но я бы предложил тогда на верхней крышке написать разноцветными весёлыми буквами Don`t panic и больше использовать ресунки, что бы и неумеющие читать всё поняли.
я тоже могу чёнить написать, но не буду.
 

sngr

AutoIT Гуру
Сообщения
1,010
Репутация
408
Не обижайся, с Don`t panic моя вольная цитата из одной хорошей книги.
Опционально - буквальный перевод слова optional
Ты меня непривильно понял - я говорю о том, что optional можно вообще не переводить, тк это элемент оформления, как содержание, поиск и тд слева, заголовок сверху и тд. Привычный элемент. Ты как автор русской справки можешь сделать как тебе угодно - мы как пользователи привыкнем к любому виду, но лучше придерживаться общепринятых стандартов.
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
AZJIO [?]
"DllClose is still a good idea" буквально переводится "DllClose всё же хорошая идея"
Думаю правильнее будет «Использование DllClose всё же будет не плохой идеей» или «Использование DllClose всё же не помешает».
 
Автор
A

AZJIO

Меценат
Меценат
Сообщения
2,874
Репутация
1,194
CreatoR
Использование DllClose всё же не помешает
да, ещё лучше.

sngr
Можно ссылочку на msdn, где именно указано по русски "опционально(ый)". Я по запросу "программирование опциональные параметры" больше встретил словосочетание "необязательные параметры", так что сомнение что "опциональные" стало стандартом, а в некоторых справочниках просто не указано.
 

sngr

AutoIT Гуру
Сообщения
1,010
Репутация
408
Насколько я понимаю, весь русский язык в msdn - это машинный перевод, поэтому встретить там можно что угодно. Но если бы здесь вместо optional было опционально я не заметил бы разницы.
 

gora

Знающий
Сообщения
315
Репутация
19
AZJIO [?]
Предлагаю ещё раз проголосовать с учётом выше сказанного и с предпросмотром
1 Почему [Необязательный] с большой буквы? Это неграмотно.
2 Почему нет варианта с [необязательный] в конце описания?
3 Почему нет пункта в Примечании для варианта ?
Условия не равные. ИМХО.
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
AZJIO [?]
Предлагаю ещё раз проголосовать
Голосование здесь не уместно, пользоваться будут сотни, а голосовать всего несколько.

Мне лично кажется что [необязательный] будет оптимальным решением.
Или, если так сильно нравится вариант с [?], то стоит задуматься над реализацией акронима, т.е чтобы при наведении на ссылку с этим вопросиком, появлялась подсказка с описанием, типа: «Данный параметр не обязательный, если параметр пропускается, то вместо значения используйте Default» (как то так :smile: ).
 
Автор
A

AZJIO

Меценат
Меценат
Сообщения
2,874
Репутация
1,194
CreatoR
Голосование здесь не уместно, пользоваться будут сотни, а голосовать всего несколько.
Я не хочу сделать хуже, или в пользу себе, поэтому я и хотел бы чтобы услышать продуманное мнение, а не потому что мы так привыкли и если поменяем вдруг будет хуже. Если будет 30% против символичной метки, думаю можно оставить ближе к оригиналу.

если так сильно нравится вариант с [?], то стоит задуматься над реализацией акронима
я уже добавил в примере выше всплывающую подсказку.


gora
1 Почему [Необязательный] с большой буквы?
для дискриминации :smile:, поправил.

2 Почему нет варианта с [необязательный] в конце описания?
добавил :smile:
3 Почему нет пункта в Примечании для варианта ?
Думаю если во всех одинаковый формат то лучше вынести это в описание к функции.
 
Верх