Все сервисы Хабра

Сообщество IT-специалистов

Ответы на любые вопросы об IT

Профессиональное развитие в IT

Удаленная работа для IT-специалистов

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

Хабр Q&A — вопросы и ответы для IT-специалистов

Получайте ответы на вопросы по любой теме из области IT от специалистов в этой теме.

Узнать больше
другие проекты хабра
  • Хабр
  • Карьера
  • Фриланс
Задать вопрос
eduardtibet

Эдуард Тибет

Technical Writer / Documentation Engineer
  • 42
    вклад
  • 2
    вопроса
  • 142
    ответа
  • 18%
    решений
Ответы
  • Информация
  • Ответы
  • Вопросы
  • Комментарии
  • Подписки
  • Нравится
  • Достижения
  • Как (инструмент ,методика) обеспечить прослеживаемость от требований через ТЗ до кода вверх и вниз?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    1. Есть системы работы с требованиями. Специально под это заточенные. Как правило, под винду. Но они НЕ являются plain text форматами. Например, вот такой подход: https://en.wikipedia.org/wiki/Software_configurati... (и, в частности https://en.wikipedia.org/wiki/Rational_ClearCase_UCM )

    2. Можно использовать single sourcing technical documentation (DocBook, DITA) c построением всей схемы работы. Вам потребуется: человек, который все это сделает и бюджет под это дело.

    Сразу скажу, что в обоих случаях удовольствие недешевое. И не факт, что п.1 будет дешевле п.2

    P.S. Предполагаю, что все-таки под контрольными примерами понимается test case.
    Ответ написан более трёх лет назад
    5 комментариев
    Нравится 5 комментариев
  • Почему APT зависает на Waiting For Headers?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Попробуйте также сменить зеркала на .de , .fi или .se - иногда помогает (если, конечно, речь идет не о security.debian.org)
    Ответ написан более трёх лет назад
    Комментировать
    Нравится Комментировать
  • Кто должен составлять документацию ( в компании) на программный продукт?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    В принципе, коллеги выше уже основную часть сказали. Добавлю от себя:
    1. Концепт системы и ТЗ - Аналитик.
    2. Планы работы и контроль их выполнения - ПМ
    3. Эксплутационная документация (руководства разного типа и вида, FAQ, HOWTO и т.п.) - технический писатель.
    4. API, SDK reference, архитектурные документы - либо технический писатель (если он высокого класса), либо разработчики.
    5. Постановка работ по документированию (типы документов, исполнители, docflow между членами команды и.т.п.) - в больших компаниях технический писатель уровня Lead. В маленьких стартапах - у кого больше опыта.
    6. Тест-планы, тест-кейсы - группы тестирования (либо лид, либо наиболее опытный)

    Для справки предыдущих участником треда: заказчики в 98% случаев НИЧЕГО не делают. Это правда жизни. Т.е. они скажут "хочу это и это", но построить из этих слов грамотную систему - см. п.1
    Ответ написан более трёх лет назад
    2 комментария
    Нравится 6 2 комментария
  • Какие есть средства организации онлайн документирования и просмотра исходного кода (C#)?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Doxygen?

    Первый вариант: по связке: SCM - выгрузка на диск - генерация - web-server. Правда, здесь онлайн документирования не будет - только документирование в коде.

    Второй вариант: SCM - выгрузка в docbook - комментарии в XML Editor applet (прямо на сервере) - генерация - web-server. Но опять же с онлайном в чистом виде (как в wiki) не будет - только через выполнение апплета на клиентской машине.

    Да, и еще... забыл добавить. Тот ресурс, который вы привели, использует статику. В нем нет возможности обновить онлайн.
    Ответ написан более трёх лет назад
    5 комментариев
    Нравится 1 5 комментариев
  • Как оформить документ "концепт" необходимых доработок ПО?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Вы сначала подумайте и решите, что вам надо - документ (который содержит подробный текстовый контент, м.б. даже с большим количеством картинок) или презентацию? Это два совершенно разных способа представления информации.

    Вам надо:
    - красиво и кратко (презентация)?
    или
    - информационно и содержательно (документ)?
    Ответ написан более трёх лет назад
    4 комментария
    Нравится 1 4 комментария
  • Как добавить изображения для всех вариаций продукта?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    А DTD/WSD/RNG что говорит по этому поводу?
    Ответ написан более трёх лет назад
    2 комментария
    Нравится 2 комментария
  • Есть сервис с функцией "согласованность содержимого"?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Все это реализовано в технологии единого источника (single sourcing technical documentation). Это функция т.н. content reuse. Термины Docbook, DITA - знакомо? Но это НЕ вики системы. Мне известно только об одном подобии этой функциональности в Confluence (и то, там она сильно урезана, т.к. не является структурированной информацией с семантической разметкой).
    Ответ написан более трёх лет назад
    9 комментариев
    Нравится 1 9 комментариев
  • Как вы документируете API?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Но, есть ли сервисы или решения, которые помогают в этом?

    doxygen?
    swagger | blueprint | RAML (for REST API)?
    single sourcing technical documentation?
    Ответ написан более трёх лет назад
    3 комментария
    Нравится 1 3 комментария
  • Где можно найти шаблон или кто может сделать ДИЗАЙН технической документации (admin guide) для MS Word?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Вы сначала определитесь, что вам надо...

    Предположу, что одно из следующих:
    1. Внешнее представление - т.к. шрифты заголовков, шрифт основной части, логотипчики и прочие няшные графический штуки.
    2. Структуру, включая названия разделов и порядок их следования.
    3. что-то еще... (что??)

    Ну и главный вопрос - ЗАЧЕМ вам дизайн? :)
    Ответ написан более трёх лет назад
    6 комментариев
    Нравится 6 комментариев
  • Инструкция по работе в Docbook, где взять?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Задавайте вопросы - подскажу. И, кстати, такие вопросы лучше писать не только в тег xml, но и тег Документация.

    И, кстати, мне очень интересно будет узнать, в каком ВУЗе или на каких курсах преподают работу c Docbook :)
    Ответ написан более трёх лет назад
    2 комментария
    Нравится 2 комментария
  • Как сделать раздел "Документация" для сайта?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    1. Упомянутый вам help.yandex.ru сделан не на php - это собираемая на кластере статика с использованием единого источника DITA. Это совершенно другой уровень. Не думаю, что вам требуются его возможности.

    2. Вы сначала определитесь с форматом, который будете поддерживать, а потом ищите приложение для отображения информации.
    Ответ написан более трёх лет назад
    10 комментариев
    Нравится 10 комментариев
  • Автомаическая генерация документации из markdown в статический сайт. Что использовать?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Вы сначала определитесь с форматом исходника, который будете поддерживать, а потом ищите приложение для отображения информации. Вас интересует Markdown?

    Например, docs.raneto.com/what-is-raneto
    Ответ написан более трёх лет назад
    Комментировать
    Нравится Комментировать
  • Какой инструмент документирования подойдет?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Традиционно со своей стороны я посоветую сначала ответить (максимально полно) на следующие уточняющие вопросы (доступны по ссылкам):

    Начать отсюда: Где посмотреть примеры документирования разработки сайта?
    Затем обязательно вот это: Как документировать существующее решение?
    И, наконец, вот это: Где лучше всего вести документацию по сервису?
    Ответ написан более трёх лет назад
    13 комментариев
    Нравится 13 комментариев
  • Cколько может стоить работа по экспорту XML?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Уточните требования. У вас сайт УЖЕ отдает XML? Т.е. требуется xslt преобразования для приведения одной xml структуры к другой xml структуре?
    Ответ написан более трёх лет назад
    2 комментария
    Нравится 2 комментария
  • Есть ли онлайн сервисы для составления документации с возможность вкрапления частей других документов?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Вам надо (одновременно):
    1. single sourcing technical documentation - Docbook или DITA.
    2. включение частей - xinclude.
    3. обработка на уровне xslt.
    Ответ написан более трёх лет назад
    Комментировать
    Нравится Комментировать
  • Как принять ПО на поддержку?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Попробуйте сначала почитать ГОСТ 24.208-80 Требования к содержанию документов стадии «Ввод в эксплуатацию». Только внимательно!

    Думаю, что после прочтения в голове сложится определенная картина.
    Ответ написан более трёх лет назад
    Комментировать
    Нравится Комментировать
  • Почему у Debian 8.2 нет обновлений?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    после этой строки:
    apt-get update

    и не будет ничего обновляться. Это всего лишь загрузка (обновление) списка пакетов.

    Чтобы посмотреть, что предполагается к обновлению:

    apt-show-versions -u

    а уже потом apt-get upgrade (если очень хочется )
    Ответ написан более трёх лет назад
    2 комментария
    Нравится 2 комментария
  • Как правильно писать документацию проекта?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    В больших компаниях (или при отлаженных процессах) этим занимается т.н. Технический писатель (Technical Writer). Далее я вам подскажу, как надо делать "по уму" без разных XP-техник и т.п. Прислушиваться к советам или нет - будете решать сами.

    В вашем случае, думаю, брать TWR смысла нет, т.к. коллектив маленький/процессы еще не отлажены. Вы, конечно, можете взять TWR для постановки процесса документирования в вашей компании, но специалисты этого уровня - это Lead Technical Writer и его расходы на него будут сравнимы с уровнем разработчика. Сразу же говорю, что никакой студент-техпис вам работу не поставит.

    Чтобы понять, что и как вам надо делать, попробуйте сами себе ответить на следующие вопросы. Я адресовал их другим участникам:
    Как документировать существующее решение?
    https://toster.ru/answer?answer_id=658763
    https://toster.ru/answer?answer_id=658763

    Имейте в виду, что некоторые участники в тех тредах с трудом анализируют информацию :)

    Можете опубликовать ответы на заданные вопросы здесь, и я постараюсь подсказать вам возможные решения.
    Ответ написан более трёх лет назад
    Комментировать
    Нравится Комментировать
  • Какую CMS выбрать для ведения документации нескольких проектов?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    Формат: Docbook/XML (начиная с 5.1) или DITA
    Хранение: GIT/SVN
    Authoring tool: любой, к которому адаптируются писатели
    Публикация - Apache Cocoon (для realtime публикации), либо скриптовая сборка (если требуется просто "отдавать файла")

    По умолчанию присутствуют:
    1. Многоязычность.
    2. Вывод deliverable в зависимости от цели (аудитория/ОС/заказчик и т.п.)
    3. Форматы: PDF, html, ePub, word roundtrip (но требуется доработка).
    4. Версионность хранения (diff/merge).

    Можно еще долго перечислять, но если действительно заинтересуют подробности (применение каждого пункта, особенности и т.п.), то дайте знать комментом.
    Ответ написан более трёх лет назад
    5 комментариев
    Нравится 5 комментариев
  • Как имея код xml, сформировать документ docx?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Technical Writer / Documentation Engineer
    docx - это zip c внутренней структурой, состоящей из xml файлов и картинок, как linked объекты.

    Ваша задача (если делать все руками):
    unzip .docx > поиск требуемого xml файла > парсинг и выцепка фрагмента внутри xml > xslt преобразование в новый xml > zip .xml > получается docx.

    Вам надо знать:
    - спецификацию docx (на структуру каталога zip файла).
    - спецификацию внутреннего xml файла.
    - XSLT (в т.ч. работа с namespace).
    Ответ написан более трёх лет назад
    Комментировать
    Нравится 1 Комментировать
Оценили как «Нравится»
  • ← Предыдущие
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • Следующие →
Самые активные сегодня
  • neuotq
    Александр Талалаев
    • 8 ответов
    • 0 вопросов
  • SoreMix
    SoreMix
    • 8 ответов
    • 0 вопросов
  • MrDecoy
    Вадим
    • 6 ответов
    • 0 вопросов
  • tyllo
    tyllo
    • 6 ответов
    • 0 вопросов
  • Василий Банников
    • 6 ответов
    • 0 вопросов
  • sergey-gornostaev
    Сергей Горностаев
    • 6 ответов
    • 0 вопросов
  • © Habr
  • О сервисе
  • Обратная связь
  • Блог

Войдите на сайт

Чтобы задать вопрос и получить на него квалифицированный ответ.
Войти через центр авторизации