Документирование ваших проектов с помощью Daux.io

Документирование проекта может быть неприятным, но это не обязательно. Существует довольно много инструментов для выполнения работы — я часто использую Daux.io из-за его гибкости.

В этой статье я покажу вам, почему вы должны документировать, как вы можете получить Daux.io и как вы можете начать использовать его прямо сейчас, чтобы сделать ваши проекты намного лучше.

Зачем нужна документация

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

Взять хотя бы Боинг 787. Этот продукт имеет обширную документацию, подтверждающую каждый аспект от проектирования до технического обслуживания. Существует даже руководство на 150 страниц, в котором описаны 787 характеристик, которые следует учитывать при планировании аэропортов.

Почему у самолета должна быть широкая документация, а у сайта нет?

Я считаю, что есть три основные причины:

• Там намного больше денег вовлечено
• Соображения безопасности
• Проблемы масштаба

У веб-сайтов редко возникают проблемы с безопасностью, но как только масштаб или деньги возьмут верх, вы можете быть уверены, что документация появится. Все крупные проекты, такие как Twitter и Facebook, содержат ошеломляющее количество информации, доступной как для разработчиков, так и для сторонних разработчиков.

Сайты, которые приносят большой доход, часто также выбирают создание хорошей документации. Идея заключается в том, что если что-то нужно изменить, каждый может обратиться к документации, и веб-сайт с меньшей вероятностью потеряет деньги из-за потери времени безотказной работы.

Означает ли это, что вы можете обойтись без документации для меньшего проекта? Конечно, вопрос в том, должны ли вы?

Преимущества документации

Документация обеспечивает общую систему координат для проекта. Преимущество этого довольно очевидно при работе в команде, но упускается из виду, когда кто-то работает один.

Если вы зарабатываете на жизнь созданием веб-сайтов, скорее всего, вы создаете по крайней мере несколько лет в год. Помните ли вы, как веб-сайт, который вы создали в январе, автоматически чирикнул свое содержимое, когда вы посмотрите его в августе следующего года? Что если компания попросит вас передать проект другому разработчику? Вы можете проводить час каждое утро, отвечая на вопросы о вашем коде на следующий месяц.

Даже самый последовательный кодер несовместим. По мере того как мы растем и учимся, мы, как правило, меняем способ работы Возможно, вы внедрили инструмент сборки, такой как Gulp, в ваш рабочий процесс, возможно, вы начали использовать объектно-ориентированный PHP.

Документация также может объяснить ситуации, которые не очевидны в самом коде. Возможно, вы специально выбрали решение, не соответствующее требованиям, просто потому, что вас попросили сделать что-то быстро, и цель оправдывала средства. Это можно добавить к документации, возможно, в качестве задачи для обновления позже.

Документирование с помощью Daux.io

Daux.io поначалу может пугать некоторых людей, потому что это не просто HTML, его можно предварительно просмотреть только с помощью сервера. Однако настроить все это довольно просто, и как только вы преодолеете это препятствие, использование будет простым и гибким.

Получение Daux.io

Самый простой способ получить Daux.io — это загрузить его с Github . Вы можете скачать пакет, используя кнопку Загрузить ZIP на правой боковой панели. Если вы опытный пользователь Github, вы можете клонировать его, или вы можете даже получить его из Packagist через композитора.

Если вы загружаете с Github, вы должны получить папку с именем «daux.io-master».

Переименуйте это в «документацию» и перенесите на рабочий стол для ясности. Чтобы написать свою документацию, вам на самом деле ничего не нужно . Вы можете редактировать файлы Markdown в любом редакторе и использовать команду, чтобы преобразовать все это в HTML для удобства обмена. Тем не менее, лучше всего предварительно просмотреть нашу работу, поэтому мы подготовимся к этому.

Предварительный просмотр документации

Для предварительного просмотра документов нам понадобится сервер. К счастью, все находится в папке проекта Daux.io, нам просто нужны предварительные условия для запуска сервера: npm и Grunt.

Установка npm и Grunt

Самый простой способ получить npm (диспетчер пакетов Node) — это установить Node. Перейдите на сайт Node и загрузите установщик. После установки вы сможете использовать команду npm в терминале (в Linux / OS X) или в командной строке (Windows).

Краткое примечание: я буду ссылаться на командную строку в Windows и на терминал в Linux / OS X с тем же словом: терминал .

Следующее, что вам нужно, это Грант . Grunt фактически устанавливается через npm, поэтому, если вы уже выполнили последний шаг, все должно быть очень просто. Откройте терминал и введите следующую команду:

Теперь у вас есть базовые инструменты, необходимые для начала работы. Если вы новичок в npm, я настоятельно рекомендую узнать больше об этом. Он позволяет легко устанавливать инструменты, и вам не обязательно знать Node.js, чтобы использовать инструменты для работы с npm (например, Grunt).

Все до этого момента необходимо только в том случае, если эти инструменты еще не установлены. Независимо от того, сколько экземпляров документации Daux.io у вас есть, вам не придется делать это снова.

Совет: узнайте больше об инструментах командной строки , прочитав серию для новичка « Командная строка для веб-дизайна » Кезза Брейси.

Пользователи Windows: установка PHP

Этот шаг предназначен только для пользователей Windows, OS X и большинство дистрибутивов Linux поставляются с предустановленным PHP, поэтому, если вы находитесь на этих платформах, вы можете пропустить этот раздел. К сожалению, установка командной строки PHP в Windows немного хлопотна, вот и все.

Перейдите на страницу загрузки PHP и возьмите ту версию PHP, которая вам нужна. При тестировании я использовал версию «VC11 x86 Non Thread Safe». Я скачал и распаковал этот архив в свою корневую папку C: / и переименовал полученную папку в «php». В конце процесса у вас должна быть папка с именем «php» в вашем основном каталоге C: /, где-то должна быть папка «php.exe».

Далее нам нужно убедиться, что команду PHP можно запустить из любого места. В Windows 7 самый простой способ сделать это — перейти в меню «Пуск», щелкнуть правой кнопкой мыши « Компьютер» и выбрать « Свойства» . Нажмите на Дополнительные параметры системы в левой боковой панели. Нажмите на вкладку « Дополнительно », затем на кнопку « Переменные среды» внизу.

Вам нужно будет нажать на путь в верхней панели, а затем отредактировать . В самом конце значения добавьте ссылку на папку, что-то вроде этого: «C: \ Users \ Dani \ environment». Это должна быть папка в вашей собственной папке пользователя. После этого сохраните все и создайте эту папку. (Если вы используете другую версию Windows, взгляните на Computerhope , в ней перечислено, как это сделать на нескольких версиях).

Внутри этой папки создайте файл с именем «phppath.cmd». Отредактируйте этот файл с помощью любого текстового редактора и добавьте следующее содержимое:

После этого перейдите в эту папку через командную строку, набрав cd %userprofile%/environment и выполните следующую команду: phppath .

Наконец, закройте командную строку и снова откройте ее, php теперь должен быть доступен глобально. Опять же, это то, что вам нужно сделать только один раз, и только в Windows.

Настройка Daux.io

Все еще в вашем терминале, перейдите в папку проекта. Помните, что это должно быть на нашем рабочем столе на данном этапе. В Windows вы можете использовать следующую команду для доступа к папке проекта:

В OS X вы можете использовать следующую команду:

Первая команда, которую вы должны выполнить, это npm install . После этого запустите npm update чтобы убедиться, что все обновлено. Эти команды устанавливают и обновляют все зависимости Daux.io. Вам нужно будет делать это для каждого экземпляра Daux.io, который у вас есть.

Запуск предварительного просмотра

Мы наконец готовы просмотреть нашу документацию. Теперь это вопрос одной команды, все, что вам нужно сделать, это ввести grunt в терминал (убедитесь, что вы находитесь в папке с документацией при вводе команды).

После нескольких секунд размышлений вы должны увидеть что-то вроде этого:

Это означает, что сервер запущен и работает, возможно, в вашем браузере уже открылась новая вкладка. Если это не так, взгляните на IP-адрес, указанный рядом с надписью «Listening on» в терминале, и введите его в свой браузер. В моем примере этот IP-адрес «127.0.0.1:8085».

Примечание : в некоторых случаях открывается вкладка, но отображается сообщение «страница не найдена» или что-то подобное. В этом случае перезагрузите вкладку через пару секунд, серверу может потребоваться немного больше времени для инициализации.

Теперь вы должны увидеть документацию по умолчанию, предоставленную в браузере. Вид, который вы видите, генерируется ad-hoc из файлов Markdown документации. Теперь, когда мы можем видеть, что мы делаем, давайте посмотрим на написание документации.

Написание документации

В папке «документация» вы должны увидеть папку «документы». Он содержит вашу фактическую документацию, все остальное для Daux.io, чтобы сделать свое волшебство. Daux.io использует специальное соглашение об именах, чтобы дать вам полный контроль над порядком страниц.

Каждый элемент на этой странице должен начинаться с цифры и подчеркивания. Чем выше число, тем ниже будет страница в документации. Если вам нужна одна страница, создайте файл Markdown (например, 04_Updating_Plugins), если вам нужна иерархическая структура страниц, создайте папку (например, 05_Code_Styling).

Текст после номера определяет название страницы в документации. Моими предыдущими примерами станут «Обновление плагинов» и «Стиль кода». Обязательно используйте только буквенно-цифровые символы и подчеркивания, подчеркивания будут преобразованы в пробелы.

С этого момента все идет гладко, все что вам нужно сделать, это отредактировать ваши файлы в стиле Markdown. Если вы не знакомы с уценкой, загляните в Таблицу уценок . По сути, это способ разметки текста (указать заголовки, ссылки, изображения и т. Д.) Без HTML-кода.

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

Целевые страницы

Еще одна полезная вещь, которую Daux.io позволяет вам сделать, — это создать целевую страницу для ваших разделов. Вся ваша документация может получить целевую страницу, если вы создадите файл «_index.md». Взгляните на пример по умолчанию, чтобы почувствовать форматирование.

Каждый раздел также может иметь целевую страницу. Если в разделе нет целевой страницы, пункт меню верхнего уровня нигде не щелкает, он просто открывает список подразделов. Если вы хотите, чтобы запись верхнего уровня имела свою собственную страницу, создайте файл «index.md» в папке для раздела.

Управление несколькими документами

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

Один из способов управления множеством потребностей в документации, например, это создание нескольких экземпляров Daux.io. Это, однако, требует, чтобы вы запускали сервер отдельно и настраивали некоторые вещи снова. К счастью, есть лучший способ!

Посмотрите на файл «global.json» в основной папке с документацией. Если вы откроете это в своем текстовом редакторе, то увидите, что для параметра docs_directory установлено значение docs . Создайте копию каталога docs, назовите его «user_docs» и добавьте в него несколько разных фиктивных файлов, чтобы можно было отличить их от оригинальной документации.

Теперь измените параметр docs_directory на user_docs и перезагрузите документацию в вашем браузере. Теперь вы просматриваете содержимое новой папки. Это позволяет легко переключаться между документами на лету, без необходимости перезагружать сервер или использовать другой экземпляр Daux.io.

Генерация итоговой документации

Конечно, в конце дня нам нужно распространять нашу документацию. Лучше всего это сделать в HTML-форме, и Daux.io поможет нам! В терминале, находясь в главном каталоге вашей документации, выполните следующую команду:

Это создаст «статическую» папку со всеми файлами HTML и активами, необходимыми для просмотра документации. Вы можете заархивировать эту папку и отправить ее кому-либо или загрузить на сервер и создать ссылку на нее.

Расширенная настройка проекта

Есть множество вещей, которыми вы можете управлять через файл «default.json». По умолчанию на боковой панели будет размещена ссылка « Сделано сегодня», а также некоторые ссылки на Twitter, которые вам не нужны или которые вы хотите настроить в своем проекте. На главной странице Daux.io перечислены опции, которые вы можете использовать в разделе «Конфигурация» далее вниз по странице. или просто обратитесь к файлу «default.json».

Вы можете использовать "twitter": ["yourtwittername"] чтобы добавить свою собственную ссылку Twitter, например. Ссылки можно контролировать с помощью параметра links , вот как добавить пару:

Вы можете найти все варианты на главной странице Daux.io. Вот пример полного файла «default.json» для воображаемого проекта.

Вывод

Настройка Daux.io поначалу может показаться сложной задачей, но это не так уж долго, особенно в системах Mac / Linux, где большая часть того, что нам нужно, уже установлена. Если вы не привыкли к терминалу и локальным серверам, привыкание к среде может занять некоторое время, но это окупится в десять раз.

Как только вы начнете работать с Daux.io, вы обнаружите, что он прост в использовании, гибок и прост в обслуживании. Ваш проект, ваш клиент, ваши коллеги и конечные пользователи вашего проекта будут благодарны вам за ваши усилия и, надеюсь, ваше время, потраченное на поддержку проекта, будет сведено к минимуму.