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

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

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

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

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

Хорошие посты про Data Science в одной коллекции
Войти на сайт
  • Все вопросы
  • Все теги
  • Пользователи

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

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

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

Эдуард Тибет

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

    eduardtibet
    Эдуард Тибет @eduardtibet
    Вот, кстати, можно вам рекомендовать. Так сказать, Manual Design HOWTO

    www.indoition.com/previews/book-designing-en-previ...
    Написано более трёх лет назад
  • Где можно найти шаблон или кто может сделать ДИЗАЙН технической документации (admin guide) для MS Word?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Да, и еще, можете попробовать посмотреть на какой-нибудь бундесбирже фрилансеров. Немчики хорошо делают дизайн - не знаю, почему. Наверное, у них развито направление Visual Art.
    Написано более трёх лет назад
  • Где можно найти шаблон или кто может сделать ДИЗАЙН технической документации (admin guide) для MS Word?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Criminal: по поводу этого:

    "Дело в том, что есть ощущение, цитата: "весь дизайн сделали сами - проще, быстрее, дешевле." — что так и выйдет. Только времени жалко на такую лабуду."

    Дело в том, что это не лабуда. Если вы сделаете сами, то вы НЕ получите:
    1. Головняка при взаимодействии со фрилансером.
    2. Срывов сроков работ.
    3. Неподконтрольный дизайн, который утечет еще хрен знает во сколько компаний.

    Да, иногда приходится заниматься неподходящими делами, но это экономит столько нервов и времени, что иногда после завершения думается: "не зря все же взялись" :)
    Написано более трёх лет назад
  • Где можно найти шаблон или кто может сделать ДИЗАЙН технической документации (admin guide) для MS Word?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Criminal:

    "Дизайн нужен, чтобы гайд выглядел нормально..." - это не ответ :) Ответ это - "чтобы продать подороже". "чтобы нас воспринимали, как крутых чуваков, способных замутить крутую документацию", и т.п.... ну, вы поняли :)

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

    Что касается минимализма, что самый что ни на есть минимализм - у DAPS (гуглите: DAPS opensuse print manual в поисках по картинкам).

    Насчет остального, то варианта два:
    1. Вбить в гугле: user manual system requirements filetype:pdf и пройтись по десятку существующих. Вторая фраза нужна для того, чтобы отсечь все руководства по хардверным штукам. Там в смысле дизайна бывает иногда такая жесть, что ...
    2. фрилансеров, как подсказывают ниже. Но, как показывает личная практика, все зависит от исполнителя. У нас было так, что в итоге весь дизайн сделали сами - проще, быстрее, дешевле.
    Написано более трёх лет назад
  • Инструкция по работе в Docbook, где взять?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Stas Karter: Вы лучше спросите, что вам непонятно :)

    1. Что это за формат хорошо написано здесь: https://ru.wikipedia.org/wiki/DocBook либо на англоязычной версии.
    2. Как делать из этого формата представление (т.е. выходные форматы) написано здесь: wiki.docbook.org
    3. Где редактировать - да хоть в Notepad, vim и т.п. Если интересует GUI, то можно попробовать www.xmlmind.com/xmleditor НО! Он стоит денег, поэтому вам, как студенту, можно использовать evaluation только в течении 30 дней. Не думаю, что вы будете его покупать.
    Написано более трёх лет назад
  • Как сделать раздел "Документация" для сайта?

    eduardtibet
    Эдуард Тибет @eduardtibet
    maximus: DITA вам не нужна, уж поверьте :)
    Если вы определились с форматом (например, Markdown), тогда дальше уже ищите примеры отображения и смотрите, каким образом это устроено у каждой системы.
    Почему так? Просто text-based форматы (adoc, md, rst) в это плане более требовательны к изначальной структуре - т.е. вы не сможете потом автоматически их разбивать на куски (про использованием sed/awk я не говорю). С xml-based форматами (Docbook, DITA) в этом смысле проще, т.к. всегда есть xslt, который разобьет вам все, как надо в любой пропорции.
    Написано более трёх лет назад
  • Как сделать раздел "Документация" для сайта?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Одна из ошибок начинающих - смотрят на интерфейс. НО! Интерфейс и формат хранения/редактирования - это две совершенно разные вещи. Вам надо сначала определить формат хранения, а потом уже под этот формат хранения искать себе морду для генерации. Только так.
    Написано более трёх лет назад
  • Как сделать раздел "Документация" для сайта?

    eduardtibet
    Эдуард Тибет @eduardtibet
    maximus: секунду... вы не поняли. Вы определились с форматом _хранения_ документации? Если да, то один путь. Если нет, то другой.
    Написано более трёх лет назад
  • Какой инструмент документирования подойдет?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Виталий Столяров: Тогда вам надо:
    1. Определить, что конкретно вы будете документировать.
    2. Надо ли вам выцеплять это автоматически.
    3. Попробовать несколько инструментов в виде теста. Про doxygen вы уже знаете. Можете еще попробовать Sphinx. Или еще погуглить. Для REST - я приводил инструменты ранее.
    Написано более трёх лет назад
  • Какой инструмент документирования подойдет?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Виталий Столяров: Вы противоречите сами себе. Приведу цитаты:
    - "сопровождение написанного кода документацией, автоматически сгенерированной из комментариев к соответствующему коду"

    однако с другой стороны вы отвечаете на вопрос:

    - "Надо ли хранить версионность всего этого добра - нет".

    Сопровождение НЕ может быть без SCM. Это принципиально.

    Давайте я объясню вам, в чем вы неправы. Вы хотите получить "что-то" и "прямо сейчас", "не задумываясь о требованиях". Я же, со своей стороны, даю советы "как надо", а не "как хочется". Безусловно, на тостере много людей, которые практически всегда отвечают не задумывась "Я использую X, попробуй", "Слышал, что Y подходит". Если вас удовлетворят такие ответы без уточняющих вопросов - без проблем - думаю вам здесь подскажут.

    P.S. И, кстати, общее решение, я уже вам привел "Если вам нужен только API, то вам будет достаточно:...." - Какой инструмент документирования подойдет?
    Написано более трёх лет назад
  • Какой инструмент документирования подойдет?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Виталий Столяров: Так в том то и дело. По требованиям выбираются инструменты и процессы, а не наоборот. Вы, конечно, можете попробовать от обратного, но это будет, мягко скажем, неоптимально :)
    Написано более трёх лет назад
  • Какой инструмент документирования подойдет?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Виталий Столяров: Виталий, по вашему ответу я уверен, вам надо основательно подумать над моими изначальными вопросами, осознать их и ответить на них. Даже, если это займет несколько дней. На текущий момент я вижу - вы смешиваете все в кучу. Т.е. вы просите подсказать вам решение конкретной проблемы, но не можете сформулировать четко эту проблему(-ы) - например, у вам по ходу диалога появляются все новые и новые требования.
    Написано более трёх лет назад
  • Какой инструмент документирования подойдет?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Виталий Столяров: Так вы сначала определитесь, нужен только API или нет? :) Т.к. разница очень большая. Если вам нужен только API, то вам будет достаточно:
    - генератора комментариев из кода.
    - что-то типа Swagger (для REST API). Здесь еще существуют другие нотации и инструментарий - RAML и WADL (последний основан на xml, первые два на json + yaml в качестве "человекочитаемого" варианта).
    - web сервер для отображения всего добра.
    - скрипты генерации (проще самописные, т.к. вариантивность маленькая).

    ОДНАКО, если вам надо делать нормальную документацию: ТЗ, архитектурные документы, руководства администратора, white papers и т.п. (т.е. то, что создается человеком, как документ, содержит иллюстрации и т.п.), то инструментарием выше вам не обойтись.
    Вам придется добавлять:
    - SCM (обязательно)
    - Authoring tools (чтобы писать)
    - generation tools + CI (чтобы все генерилось без участия человека).

    Если вероятность расширения продукта велика и вынос наружу будет (а это только вам решать), то следующие элементы в структуре must have:
    - SCM
    - Authoring tools
    - CI

    Лично я занимаюсь сложными системами, и, конечно, мог бы вам посоветовать использовать много чего, но все-таки вопросы цены внедрения/сопровождения имеет немаловажное значение. Не зря я вам посоветовал посмотреть Где лучше всего вести документацию по сервису? - это напрямую относится к деньгам при выборе решения.
    Написано более трёх лет назад
  • Какой инструмент документирования подойдет?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Виталий Столяров: И еще... как я понимаю, нужен только API и все? Т.е. никаких руководств, архитектурных решений и т.п. (т.е. "нормальных документов") не нужно.
    Написано более трёх лет назад
  • Какой инструмент документирования подойдет?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Виталий Столяров: п.2 противоречит п. 1, а также пункту "для чего". Печатка нужна только для распространения наружу. Вы не будете печатать у себя + искать внутри. Вам нужен только html c поддержкой поиска.
    п.7 - вы уверены в том, что вам не нужно будет держать версионность? Т.е. вопрос коллеги типа "а как там у нас это было реализовано в предыдущей останется без ответа" (точнее, без ответа из документации).
    Написано более трёх лет назад
  • Cколько может стоить работа по экспорту XML?

    eduardtibet
    Эдуард Тибет @eduardtibet
    На уровне XSLT вопрос не в количестве добавляемых объектов (хоть 5, хоть 1000), а в сложности логики добавляемых элементов. Написать обычное xslt преобразование, добавляющее внутрь всех элементов А элемент B - дело 5 минут. Другое дело, что кто возьмется за такое.
    Написано более трёх лет назад
  • Не могу настроить svn сервер?

    eduardtibet
    Эдуард Тибет @eduardtibet
    digiben: У вас две несовместимые вещи по требованию надежности: _старый_ системник и svn (т.е. src). Думаю, что VPS + backup на старый системник (или другой компьютер) будет лучше. Тем более, что VPS можно найти и за 200 рублей в месяц (ну, естественно, c использованием только по IP без NS).
    Написано более трёх лет назад
  • Почему у Debian 8.2 нет обновлений?

    eduardtibet
    Эдуард Тибет @eduardtibet
    danwerspb Да, и еще...
    1. По умолчанию, все пакеты с устраненными уязвимостями идут из secutiry (http://security.debian.org):
    2. Ubuntu - это уровень debian sid (о том, что такое sid: https://www.debian.org/releases/sid/index.ru.html)
    3. Не знаю, как в Убунте, но в дебиане stable на десктопе прилетает максимум 10 пакетов-обновлений в неделю.
    Написано более трёх лет назад
  • Какую CMS выбрать для ведения документации нескольких проектов?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Денис _______________: Я согласен, что разные подпорки существуют. Я лишь высказал свое мнение относительно изменяемых URI - это very bad practice.
    Написано более трёх лет назад
  • Какую CMS выбрать для ведения документации нескольких проектов?

    eduardtibet
    Эдуард Тибет @eduardtibet
    Вся суть в том, что вам надо совсем отстранить "студентка-техписательницу" от какой-либо структуры и здесь это можно сделать. Т.е. вы даете ей редактор (в моей схеме - Authoring tool) и она там пишет - все. Остальное - цепочки преобразований, топиков и т.п. остается на уровне автоматизации. Здесь только один вопрос - сможет ли она владеть чем-то "не ворд" для набивания текста. По моему опыту - научить реально, хотя и с усилиями.

    Вы можете попробовать (просто сделать один шаг) - загрузить www.xmlmind.com/xmleditor evaliation. Посмотреть сюда, как это работает: www.xmlmind.com/xmleditor/tutorial.html Хотя сразу же предупреждаю, что там по умолчанию все основано на gui-действиях и оно дольше, чем сделать keyboard shortcuts.

    Вам надо понять только одну вещь - wiki и другие WISYWIG системы хороши для создания контента сотрудниками с нулевым уровнем знаний :) ... но ровно до тех пор, пока контентом не надо управлять. Когда начинается серьезная работа, то без single sourcing уже не обойтись.
    Написано более трёх лет назад
  • ← Предыдущие
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • Следующие →
Самые активные сегодня
  • SoreMix
    SoreMix
    • 12 ответов
    • 0 вопросов
  • firedragon
    Владимир Коротенко
    • 8 ответов
    • 0 вопросов
  • sergiks
    Сергей Соколов
    • 7 ответов
    • 0 вопросов
  • delphinpro
    Сергей delphinpro
    • 6 ответов
    • 0 вопросов
  • DevMan
    DevMan
    • 6 ответов
    • 0 вопросов
  • Drno
    • 6 ответов
    • 0 вопросов
  • © Habr
  • О сервисе
  • Обратная связь
  • Блог

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

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