Как и где хранить техническую документацию?

Question

[FlipWho]

Привёл в порядок инфраструктуру в Компании и пришла пора документации. В каком виде хранить и где?

Answer 1

[Артемий]

DokuWiki

Answer 2

[DDDsa]

Хороший подход — docs as code.
Мы ведём все документы в git-репозиториях, в формате Markdown. Исходники обёрнуты в Foliant, который может в любой момент из md собрать PDF, docx, сайт, гугл-док или что угодно. Например, многие проекты с документацией автоматически собираются в базу знаний при помощи GitLab-CI. При каждом пуше изменений в репозиторий сайт пересобирается и мы уверены, что там всегда свежие доки. А как только менеджер просит готовый документ — можно тут же собрать PDF, с коропоративным лого и т д.

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

Answer 3

[Дмитрий]

Knowlage base - спейс в корп. Confluence
Инфраструктуру, кабельную документация и описание серверов-свитчей - Racktables.

Comments

[FlipWho]

Дмитрий, спасибо за ответ. А есть возможность затёртые скрины запостить? Как это выглядит не в демке от разработчиков, а в боевом режиме?

[Дмитрий]

что именно, Confluence или Racktables ?

Добавил:

Конфлюенс - это wiki на стероидах, отличная база для документации, есть даже не очень дорогие варианты.
с Racktables сложнее, его показать не смогу - трудно замазывать, там имена - адреса - описания.
Но его наверняка можно поставить в докере, чтобы посмотреть , займет не много времени.

[FlipWho]

Дмитрий, по-хорошему, и то, и то хотелось бы увидеть на живом примере.

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

Конфлюенс - ушёл смотреть, но Атласиан уже попахивает тяжелым "комбайном"...

[Дмитрий]

Конфля - да, комбайн. Но мне выбирать не приходится - это корп стандарт и нам просто дали тут место ). На самом деле мне нравится - еще бы работало оно побыстрее, но это другой вопрос.

Racktables трудно описать. Это скорее процесс. Смотрите. Я добавляю туда свои подсети. Добавляю устройства. Скажем при добавлении сервера я описываю какой адрес на его интерфейсе и в разделе сетей этот адрес сразу резервируется. То есть там все разделы связаны, всегда виднона какой порт свитча что подключено, какой порт на сервере, какая там система, чтото еще. Но конечно как и любая другая документация - надо поддерживать ее актуальной, иначе очень скоро она превращается в бесполезную тыкву.

[FlipWho]

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

[Павел Межуев]

Confluence так себе на самом деле. Тоже его используем, но выбрали исключительно из-за интеграции с Jira Service Desk. У него есть просто детские болезни, висящие в баг-трекере Atlassian годами со статусом «GATHERING INTEREST» или «FUTURE CONSIDERATION», да и базовый функционал достаточно скромен. Поэтому рекомендую посмотреть в сторону свободных WIKI-движков.

Answer 4

[Эдуард Тибет]

Если не хотите тыкать пальцем в небо, а нужен системный подход без факапов, начните изучать тему отсюда: Как лучше сделать документацию компании? и далее по ссылкам в том посте.

P.S. Неоднократно замечаю интересный факт. Все советуют решение, о котором вроде бы слышали или которое работает конкретно у них, но никто не задается главным вопросом: а какая цель у ТС? Какие входные условия у ТС? Участники треда, вы понимаете, что выбор инструмента/подхода - это не выбор из А, B, C. Это, в первую очередь, определение цели (они могут различаться на 180 град.), анализ входных условий и только потом выбор инструмента/подхода. Если у конкретного участника этого топика работает инструмент/подход, который приносит ему пользу, то это совсем НЕ означает, что такой же подход с таким же успехом будет обязательно работать у топикстартера.

Answer 5

[Владимир]

моя эволюция:
1 куча txt
2 redmine
3 confluence

Comments

[FlipWho]

Спасибо за ответ!
Есть ли возможность пару скринов с дельными советами по организации с нуля мне дать? Замазать конф данные конечно.

[Владимир]

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

Бюрократия и контакты
Интернет провайдер (договора счаета и тд)
Домены и инфа по ним ( договора сроки продления где зарегистрированы и тд)
Лицензии на софт (антивирусы винда чтото еще)
Прочие контакты (замена катриджей, ремонт домофона, электрик Петрович)

[FlipWho]

Владимир, Спасибо!

Answer 6

[moropsk]

xwiki
https://www.xwiki.org/xwiki/bin/view/Main/WebHome

Comments

[FlipWho]

Спасибо за участие!
Ну и по традиции - есть возможность сделать скринов с советами по наполнению? Ну и "заквадратить" конф.данные.

Answer 7

[Кирилл Горелов]

docsify + gist.github.com

Answer 8

[other_letter]

Тут многие пишут конкретные решения.
А я советую любой WIKI. Какой душе угодно. Сейчас Вы не поймёте прелестей совместной работы и прочего, что даст Вам продукт посерьёзнее.
А так - ветки есть, связность без проблем, версионность опять же. Совместная работа, комменты - да всё это в любом известном мне вики-движке есть

Answer 9

[vlarkanov]

confluence

Answer 10

[Sergey Ryzhkin]

Доки во всяких Wiki.
Файлы конфигов в Git (и аналогах), можно откатиться и т.д., все по рукой, видно когда что менялось.
Схема можно в банальном Visio.

Раньше инфу по компам и принтерам держал в связке GLPI+FussionInventory, там же кстати была база FAQ

Answer 11

[CityCat4]

redmine. В нем есть и хранилище документов и вики. Схемы в Visio. Конфиги и прочую текстовую байду - в SVN

Answer 12

[lonelymyp]

зоопарк doc файлов на ftp
плачу и рыдаю
написал чтоб просто пожаловаться.

Answer 13

[Dmitry]

Confluence, Netbox

Answer 14

[zxosa]

Любой Wiki + основополагающие вещи в бумаге обязательно (исполнительная документация и другие планы и схемы, к примеру)

Answer 15

[ekopiy]

Sphinx+тема readthedocs+git+иногда интеграция plantuml отлично подходят для документирования исходников, api, программных продуктов, веб-интерфейсов, алгоритмов, да и просто текста. Де факто стандарт для ИТ, очень удобный и красивый

Comments

[Сергей]

Возможно, автор этого комментария имел ввиду вот этот пост.

[ekopiy]

Сергей, почти так. Только в посте описан способ хостинга на readthedocs, который является публичным в бесплатной версии. А это не всегда подходит. Вот примеры доков, на которых я учился:
https://sphinx-ru.readthedocs.io/ru/latest/sphinx.html
https://m.habr.com/ru/post/151129/
Sphinx-doc.com

[Andrew Lewman]

AndrewRusinas давай присмотримся