РЭ: ошибки в описании процесса обновления ПО аппаратуры MC04-DSL-3U

[alx]

В РЭ аппаратуры MC04-DSL-3U редакции 39 в разделе 6.2.26 на странице 186 описаны способы обновления ПО.

В описании я вижу много ошибок, а также непоследовательность и неполноту описания.

В описании варианта обновления с сайта предприятия-изготовителя указан хост www.adc-line.ru. Это неверно. Серчер предприятия-изготовителя, на котором находится репозиторий, имеет имя хоста repo.adc-line.ru.

Далее говорится, что для обновления с сайта предприятия-изготовителя необходимо скачать пакеты обновлений с сайта
предприятия-изготовителя по ссылке ​http://adc-line.ru/catalog/msan/3u/. Во-первых, указанная ссылка ведет на веб-страницу описания аппаратуры MC04-DSL-3U, и никаких пакетов там нет. Во-вторых, для обновления с сайта предприятия-изготовителя ничего скачивать не надо. Аппаратура сама скачает все, что ей необходимо для обновления. Все, что нужно сделать для обновления ПО - это нажать кнопку "Проверить обновления", а затем, после завершения проверки, нажать "Установить выбранные пакеты".

Далее написано:

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

Непонятно, где "там"? На сервере предприятия-изготовителя? Так читатель уже читает руководство по эксплуатации, полученное с сайта предприятия-изготовителя (чем не инструкция?)! Не лучше ли описать процесс прямо там, не отсылая к каким-то другим источникам?

Далее написано:

Также возможно использование стороннего сервера, поддерживающего протоколы HTTP или FTP.

Это правда, но это не вся правда. Кроме перечисленных протоколов также поддерживается обновление по протоколу HTTPS.

Далее написано:

Пакеты обновлений на сторонний сервер можно загрузить с сайта предприятия-изготовителя, используя команду wget -m -nH -cut-dirs=2 ​http://adc-line.ru/feeds/sw-01/ipk.

Здесь (кроме замены URL, о которой я писал выше) я бы добавил "например":

загрузить с сайта предприятия-изготовителя, например, используя команду wget

чтобы подчеркнуть, что это всего лишь один из возможных примеров, и читатель может копировать наш репозиторий теми инструментами и теми способами, какие ему более удобны.

Далее подробно описан, собственно, процесс обновления. Мне не нравится такая компоновка информации. В самом начале читателю сообщается, что самый простой способ обновления - это обновление непосредственно из репозитория АДС. Однако прежде чем он прочитает о том, как же этот самый простой вариант делается, он видит целую кучу ненужной в этом случае информации, типа как можно скачать копию репозитория на свой компьютер.

Мне кажется, более удобным для читателя было бы сначала полностью описать самый простой способ - обновление из репозитория АДС. То после указания, что это самый простой способ, сразу написать: "Нажмите кнопку Проверить обновления (строка URL для обновления должна оставаться пустой)..." и т.д. А затем написать: "если доступ платы SW-01 к репозиторию АДС по каким-то причинам невозможен, можно выполнить обновления с любого другого сервера, к которому доступ есть". Далее описать, как сделать копию репозитория, как проще поднять свой сервер и т.п. А затем написать что-то типа: "Укажите в строке URL для обновления путь к копии репозитория, а далее следуйте описанной выше процедуре обновления из репозитория АДС". При такой компоновке материала те, кто может обновиться напрямую через интернет, могут просто не читать оставшийся текст о том, как поднимать свой сервер и копировать репозиторий...

Далее есть такой текст:

Возможно несерийное обновление ПО в плате SW-01...

Лично мне здесь непонятно слово "несерийное". Из этого текста вытекает вывод, что обновление ПО может быть "серийное" и "несерийное". Но что это означает, и в чем различие этих категорий, в тексте РЭ не поясняется. Подозреваю, что это слово будет непонятно не только мне, но и другим читателям РЭ, поэтому предлагаю либо добавить разъяснение, что такое "серийный" и "несерийные" обновления, либо исключить слово "несерийное" из текста РЭ.

Наконец, в самом начале п. 6.2.26 говорится о трехисточниках обновления:

• сервер обновлений на сайте предприятия-изготовителя;
• сторонний сервер;
• локальный компьютер.

Два первых пункта понятны и описаны. Третий, насколько я понял - это установка отдельных пакетов через веб-интерфейс (кнопка "Установить .ipk"). Если так, то предлагаю сформулировать эти варианты более точно, например так:

• из репозитория АДС через интернет:
• из копии репозитория на стороннем сервере;
• установка отдельных пакетов через веб-интерфейс.

[san]

Да, в этом пункте всё очень сумбурно.
Думаю, что возьмусь переформулировать содержание этого пункта.

[san]

Предлагаю полную замену текста в п 6.2.26:

6.2.26 Вкладка Обновление ПО / Загрузка обновлений ПО в плату SW-01:
Обновление ПО в плате SW-01 можно осуществить следующими способами:

• обновление через интернет из репозитория предприятия-изготовителя
• обновление с локального ПК
• обновление из копии репозитория на стороннем сервера
• установка отдельных пакетов ПО

1. Обновление через интернет с репозитория(сервера обновлений ПО) предприятия-изготовителя.

Самый простой вариант – использовать в качестве источника сервер обновлений предприятия-изготовителя. Этот вариант возможен при наличии у обновляемого оборудования доступа из сети технологической связи к сети Интернет.
1.1 В веб-интерфейсе платы SW-01 на вкладке "Обновление ПО" нажмите кнопку "Проверить обновления"(строка "URL для обновления" должна оставаться пустой). Будет произведено сравнение версий ПО, находящегося на плате SW-01 с версиями ПО, находящимися на сервере обновлений. Ход выполняемых действий будет отображаться в окне "Результат:", пример на Рис. 6.49. Ход действий отображается в виде служебных сообщений. Проконтролируйте отсутствие сообщений об ошибках.
1.2. После проверки наличия обновлений появится таблица "Список доступных обновлений:", содержащая перечень пакетов, для которых на сервере обновлений появилась новая версия. Пакеты представляют собой контейнеры определенного формата, содержащие в себе файлы загрузки, метаданные и управляющие скрипты.
1.3. Если иного не оговорено со службой технической поддержки, то рекомендуется нажать кнопку "Выбрать все" для установки всех пакетов обновлений. Затем нажать кнопку "Установить выбранные пакеты". Доступные обновления плат блока будут загружены в плату SW-01.

2. Обновление с локального ПК, подключенного к блоку MC04-DSL-3U.

2.1. Скачать архив с обновлениями(ссылки на архив и историю изменений ПО размещены на страничке оборудования MC04-DSL-3U ​http://adc-line.ru/catalog/msan/3u/).
2.2. Распаковать архив на локальный ПК. Внутри архива, кроме пакетов обновлений, содержится подробная инструкция обновления.
2.3. Обновить ПО платы SW-01 следуя приложенной инструкции.

3. Обновление со стороннего сервера.

Для обновления возможно использование стороннего сервера, поддерживающего протоколы HTTPS, HTTP или FTP.
3.1. Загрузить пакеты обновлений на сторонний сервер из репозитория предприятия-изготовителя ​https://repo.adc-line.ru/sw-01/ipk/ . Для загрузки можно, например, использовать команду wget -m -nH -cut-dirs=2 https://repo.adc-line.ru/sw-01/ipk/.
3.2. В графу "URL для обновления" в веб-интерфейсе платы SW-01 ввести местоположение пакетов обновления.
3.3 Нажмите кнопку "Проверить обновления". Будет произведено сравнение версий ПО, находящегося на плате SW-01 с версиями ПО, находящимися на сервере обновлений. Ход выполняемых действий будет отображаться в окне "Результат:". Проконтролируйте отсутствие сообщений об ошибках.
3.4. После проверки наличия обновлений появится таблица "Список доступных обновлений:", содержащая перечень пакетов, для которых на сервере обновлений имеется новая версия.
3.5. Если иного не оговорено со службой технической поддержки, то рекомендуется нажать кнопку "Выбрать все" для установки всех пакетов обновлений. Затем нажать кнопку "Установить выбранные пакеты". Доступные обновления плат блока будут загружены в плату SW-01.

4. Установка отдельных пакетов ПО

В исключительных случаях возможна установка отдельных пакетов ПО пользователем. Пакеты для обновления могут быть предоставлены пользователю службой технической поддержки предприятия-изготовителя (файлы с расширением *.ipk).
4.1. Нажать кнопку "Установить .ipk". Откроется окно, как показано на Рис. 6.50:
Рис. 6.50 Установка отдельного пакета ПО в плате SW-01 из файлов типа *.ipk
4.2. Нажмите кнопку "Выберите файл"
и выберите на локальном компьютере файл пакета с расширением *.ipk, затем выберите для данного файла пакета соответствующий файл подписи с расширением *.sig и нажмите кнопку Установить.
Повторите действия, описанные выше для всех пакетов, которые необходимо установить.

[alx]

Replying to san:

Предлагаю полную замену текста в п 6.2.26:

• обновление с локального ПК
• обновление из копии репозитория на стороннем сервера

Я по-моему с самого начала это заметил, но в описании тикета этого нет: два перечисленных выше способа - это на самом деле один и тот же способ, ведь локальный ПК - это тоже сторонний сервер! И инструкция из архива по сути повторяет инструкцию из текста РЭ: поднять сервер с копией репозитория, ввести его адрес в веб-интерфейсе и нажать "Проверить обновления"...

Предлагаю объединить эти два пункта в один.

[alx]

И еще, Саша, извини что придираюсь к мелочам, но я на 99% уверен, что Vladimir просто скопирует твой текст в РЭ без какого-либо редактирования, поэтому высказываю просьбу: когда идет перечисление действий, используйте, пожалуйста, глаголы в одной и той же форме, единообразно. Либо в неопределенной:

• открыть...;
• ввести...;
• нажать...;

либо в повелительном наклонении:

• откройте...;
• введите...;
• нажмите...;

А то когда разные формы смешаны в одном логически связанном списке, это выглядит... даже не знаю как сказать... плохо выглядит. :)

[alx]

Replying to alx:

• обновление с локального ПК
• обновление из копии репозитория на стороннем сервера

Предлагаю объединить эти два пункта в один.

А вот чего я не увидел в предлагаемом тексте, так это обновления из консоли. Почему? Оно ведь уже было в РЭ... Или оно где-то в другом пункте, не в 6.2.26?

[san]

плохо выглядит

Согласен, но честно говоря, в части согласования предложений, пунктуации и орфографии я всё-таки надеялся на Vladimir-а.

Предлагаю объединить эти два пункта в один.

Я намеренно оставил разделенными эти пункты хоть и по логически это один и тот же.
По моему опыту ~90% пользователей используют именно вариант "обновление с локального ПК" поэтому на него более узкая, отдельная инструкция.

обновления из консоли

Т.к. работа с консолью у нас в РЭ не описана, а лишь упомянута, что я считаю правильно, то и обновление из консоли описывать нет смысла. Если вдруг кому то понадобится - они получат эту информацию через техподдержку.

[alx]

Replying to san:

Т.к. работа с консолью у нас в РЭ не описана, ... то и ... описывать нет смысла.

Странная логика... По такому принципу ничего в РЭ описывать не надо, чего там пока еще нет...

[san]

Я имел в виду, что вообще работу в консоли мы в РЭ не описываем, не только обновление но и всё остальное. Думаю что и не надо.

[alx]

Replying to san:

не только обновление но и всё остальное.

Стал вспоминать, что еще может потребоваться делать в консоли кроме opkg. Вспомнил только смену пароля командой passwd. Открыл РЭ - passwd описана. :)

Думаю что и не надо.

Хорошо. Не буду настаивать. Просто странно, что удалили то, что уже когда-то было описано...

[san]

Описание смены пароля - вынужденная мера, т.к. дефолтный пароль это дыра в безопастности и мы обязаны сообщить пользователю об этом, если когда нибудь в дефолте будет авторизация по ключу(как в VE-01), то и об этом упоминать не нужно будет. Всё-таки я считаю, что работа с консолью в нашем оборудовании это исключительный случай, выходящий за рамки РЭ.
Удалили когда-то раньше, я не удалял сейчас.

[san]

глаголы в одной и той же форме ... в повелительном наклонении:

Не выдержал, исправил)

[Vladimir]

Все изменения вставил в РЭ-42, файл с изменениями приложен в ЛТ
(см задачу "Правка в разделе Обновление ПО").

[alx]

Replying to Vladimir:

(см задачу "Правка в разделе Обновление ПО").

Где эту задачу можно посмотреть?

[Vladimir]

Эта задача в ЛидерТаске, который установлен уже почти у всех,
а вот тебя, оказывается, там почему-то нет...
Попробовал прицепить этот файл сюда, см. выше.

[san]

Milestone deleted