Чи слід використовувати Git для документації та управління проектами? Чи повинен бути код в окремому сховищі?

Я запускаю сховище Git для групового проекту. Чи має сенс зберігати документи в тому самому сховищі Git як код - схоже, це суперечить природі потоку редагування git.

Ось короткий опис моїх питань:

• Чи буде стиль редагування Git заплутаним, якщо і код, і документи перевіряються в одному сховищі ? Досвід з цим?

• Чи добре підходить Git для контролю перегляду документації?

• Я НЕ запитую, чи Система контролю ревізії взагалі повинна або не повинна використовуватися для документації - вона повинна.

Дякуємо за відгук поки що!

Ми постійно зберігаємо документацію у SVN. Насправді весь наш посібник користувача написаний у LaTeX та зберігається у SVN. Ми вибрали LaTeX спеціально, оскільки це текстова мова, і легко показувати, що рядки за рядком відрізняються.

Ми також зберігаємо деякі неформатні формати, наприклад файли Microsoft Office .doc, розкладені аркуші, .zip файли тощо, коли це необхідно ... але частина користі RCS втрачається, коли ви не бачите інкрементального відрізняється.

Головне - переконатися, що ваша документація добре організована, щоб люди могли знайти (та оновити) документацію (та джерело), ​​коли вони потребують.

Ну, це залежить від того, який формат ви використовуєте для документації. Якщо це щось на основі тексту, це все добре.

Git також може зберігати бінарний вміст і ви можете відстежувати версії, але різний вихід не матиме сенсу.

Також можливо зберігати документацію в самому коді, як perldoc pod, java також має для цього певний формат / анотацію.

Я не можу уявити, чому ви вважаєте, що може виникнути проблема з використанням git або будь-якої іншої системи контролю версій для документації. Як і вихідний код, документація повинна мати повну історію та можливість повернутися до більш ранньої версії, якщо це стане необхідним. Для цього ідеально підійде система управління версіями.

Зрозуміло, що використовувати якусь систему управління версіями для зберігання документів - це нобрейдер. Цікавіша частина питання полягає в тому, чи корисно зберігати документи в одному і тому ж місці в якості вихідного коду? Можлива проблема тут полягає в тому, що в цьому випадку може бути важко встановити різні привілеї доступу для коду та документації. І у багатьох ділових випадках людям знадобиться доступ до документів, але не вихідний код, як-от маркетинг або бакалаврські відділи.

У компанії, на якій я працюю, ми складаємо документацію в SVN. Однак після кількох конфліктів і необхідності поділитися ним ми вирішили перенести його на Mediawiki.

Спочатку це було trac, після чого переїхало до Mediawiki, тому що його було легше використовувати ...

Основна проблема SVN полягала в тому, що ми мали систему авторизації для SVN.

• Мати більше, ніж просто вихідний код у сховищі, - це дуже гарна річ.

  Він об'єднує всі ваші ресурси разом і перетворює проект у згуртовану, централізовану сутність, а не розсіяну колекцію файлів. Співробітники / працівники знають, де їх знайти, а не надсилати "Де я можу змінити документацію для функції x?" електронні листи.

  Ви хочете все організувати. Створити систему відокремлення srcвід imagesвід docs. Ви завжди можете додати a .gitignoreдо каталогу, щоб зберегти сховище та історію чистими. Оскільки Git-файли засновані на файлах, * ви можете від'єднати зміни джерела від змін документації так сильно, як вам подобається.

• Як уже говорили інші, Git чудово підходить для версії документації, якщо це текстова версія.

• Я повністю згоден; Документацію слід узгоджувати прямо поряд із кодом.

Моя правдоподібність походить від того, що я користувач GitHub, і беру участь у одному проекті та досліджую багато інших. На мій досвід, повний, єдиний проект легко розказати з напівзниклого. Я намагаюся містити всі мої проекти в одних каталогах, коли це можливо.

Я прийшов сюди зі схожим запитанням. Ми походимо з SVN-середовища, де в основному не вимагає зберігати всі матеріали, пов'язані з проектом, в одному сховищі. Завдяки природі SVN ви можете легко перевірити частини сховища, тому якщо вам просто потрібен вихідний код (наприклад, розгортання веб-сайту), це не проблема.

З Гітом все інакше. Каса завжди знаходиться на рівні кореня, тому якщо ви хочете розмістити все в одному сховищі, ви завжди будете мати однакову структуру каталогів. Один із підходів, який я натрапив, - це розмістити все в окремі гілки, тобто у вас є кодові гілки (які, як правило, є вашими звичайними гілками, розробниками тощо), і док-гілка, яка має свою окрему структуру каталогів. Я ще не впевнений, що це найкраща ідея, але це пропозиція, яка обходить проблему, яку, на мою думку, лежить в основі вашого запитання.

Я використовую вікі для внутрішніх документів ... отримати редакцію PLUS видатного доступу / простого редагування. Коли документація не синхронізована, оновіть її тут і там. Для документації для кінцевих користувачів розгляньте такий професійний інструмент, як Madcap Flare. Вони використовують діалект XML для обміну, складання та перетворення документації.

У коді думки, як правило, розділяються по черзі. Я схильний писати документацію з м'якими лініями обгортання. Коли я виконую ці файли, рядки є цілим абзацом. Це не дуже корисно читати в git diff. Це проблема, яку я намагався вирішити, коли переглядав Google і знайшов цю сторінку. Дякую Арну Хартерзу за те, що познайомив мене git diff --word-diff. Вам може сподобатися git diff --color-wordsще краще.