LOGO JQbook
Ведение документации по проекту

Ведение документации по проекту


При работе с несколькими проектами возникает необходимость вести локальную документацию. Для хранения сведений.

Это помогает не забывать важные вещи.

Коллективные системы

Системы коллективного ведения проектов (баг трекеры, trello, google docs и тп) -- не рассматириваются.

Так как, если они есть вы их будете использовать.

Локальная документация

Локальная документация аккумулирует сведения о проекте таким образом, что если исчезнет доступ к "коллективной системе", все сведения остануться при вас.

Формат заполнения достаточно свободный, без ограничений.

Контроль версий

Используется GIT/Mercurial(hg) локальный/удаленный репозитарий

Система контроля версий удаленного репозитария все равно создает локальную папку идентичную удаленной.

Поэтому проблем портабельности данных не возникает.

Контроль версий контролирует только код лежащий в папке Source или иной папке.

Документация не использует контроль версий.

Формат данных

Документация ведется в формате MD и ODS
Папка с проектом может быть упакована в ZIP архив, и быстро перенеса на флешку или любое удобное место.

Главный принцип - портабельность данных.

Структура папок проекта

Проект может иметь отдельную папку с исходным кодом, запускаюмую на WebServer, или любом другом удобном для исполнения месте.

- readme.md - основые сведения о проекте
- Документация - папка с документацией
- - - данные.odt
- - - ...
- [Resources | Images] - изображения, и тп
- SOFT - программное обеспечение для работы
- MHT - интернет статьи в формате MHT ODS ODT MD PDF HTML
- Source - папка с исходным кодом
- GITSource - папка с используемыми библиотеками

Документация

В данной папке лежит документация по проекту:
- спецификации
- тех-задание
- специфическая проектная информация (структуры классов, замечания по архитектуре и тп)
- ваши личные заметки

SOFT

В папке хранится все программное окружение (или ссылки на него) для разворачивания работы над проектом на другой машине.

Данная папка может содержать:

- бинарные установочные пакеты программ, которые используются в проекте
- ссылки на программы
- инструкции по установке

MHT

Технологии развиваются стремительно, в такой ситуации важные сведения выискиваются в интернете, к тому же нельзя знать все.

Данные найденные в интернете можно сохранять в MD файлик.
Однако это долго.
Гораздо проще использовать MHT формат, и сохранять веб страницы целиком.
Можно разбить на подпапки.

Также в этой папке может лежать все, что нельзя положить в папку Документация.

GITSource

В данной папке хранятся:
- ThirdParty исходники (с репозитария github), подключаемые или используемые в проекте
- другие исходники
- все что нельзя поместить в папку Source

Примеры

Базовая структура папок, для разворачивания проекта.

 sample.zip