Pull to refresh
  • by relevance
  • by date
  • by rating

Использование asciidoc для документирования проекта

Project management *
Когда перед нашей фрилансерской группой встала задача документирования проекта, были сформулированы следущие требования:
  • Как известно, программисты, обычно, не очень любят писать документацию… поэтому чем проще и комфортнее будет её писать, тем больше вероятность, что её таки будут писать.
    • Поскольку мы работаем из дома, то должна быть возможность писать документацию локально, на своей машине.
    • Чтобы это было делать комфортно, нужна возможность использовать для этого любимый текстовый редактор, никаких форм на вебсайтах а-ля вики или систем заточенных под конкретный редактор/IDE.
    • С доступом в инет у всех по-разному, и чтобы исключить ситуацию, когда документация небыла написана исключительно потому, что когда появилось настроение её писать по закону подлости отвалился инет — для написания документации не должен требоваться инет.
  • Документация должна быть доступна всем, кто работает над проектом. Это включает как возможность читать её через вебсайт так и работать с ней как с обычными локальными файлами.
  • Желательно, чтобы документация поддерживала какой-нить язык разметки и гиперссылки, чтобы её было удобно читать.
  • Возможность редактировать документацию из браузера (а-ля вики) желательна, но не очень важна (разработчики будут работать с файлами, так что эта фича может пригодиться в основном клиенту, который врядли будет напрямую править документацию).

Читать дальше →
Total votes 29: ↑27 and ↓2 +25
Views 21K
Comments 22

Haskell: а мне можно?

Lumber room
Заметка для тех, кто не только слышал всякое про Haskell, но еще и заинтересовался этим…

Привожу несколько ссылок для тех, кто хочет понять, что же такого «здоровского» в этом языке программирования, и с чего начать:В общем-то, все приведенные ссылки, кроме одной (угадайте, какой) предполагают наличие весьма неплохого знания технического английского языка.
Возможно, эта информация покажется вам не очень полезной, но, по крайней мере, позволит определиться с вашим личным отношением к этому языку программирования.
Total votes 5: ↑5 and ↓0 +5
Views 843
Comments 2

Документация по Django в одном файле

Django *
Один хороший человек взял и скомпилировал всю документацию из
www.djangoproject.com/documentation
в виде одного CHM-файла. Честь ему и слава!

Уже пользуюсь больше месяца, удобно.

Скачать можно отсюда:
charupload.wordpress.com/2007/12/02/django-documentation-chm
(1,3Мб)
Total votes 12: ↑9 and ↓3 +6
Views 5.5K
Comments 9

Bulldoc 0.2 Released

Lumber room
Выпустил 0.2 релиз своей Бульки. Прислушался к замечаниям, спасибо друзья. Переделал сайт, все-таки должен быть сайт, а не одиноко лежащая документация.
Изменения в этом релизе:

  • Проект приобрел svn репозиторий
  • В документацию добавлены разделы: Быстрый старт и Авторы. Внесены изменения в разделы конфигурации книжной полки, работы с оглавлением, работы с текстом и др.
  • Конфиг книжной полки переведен в YAML, и значительно упрощен
  • Упрощен формат файла оглавления: простые страницы задаются просто парой файл-заголовок
  • Сделана подсветка синтаксиса на основе GeSHi


Подробнее можно прочитать на странице релиза.
Total votes 8: ↑8 and ↓0 +8
Views 200
Comments 4

BullDoc 0.3 Released

Lumber room
Выпущена очередная версия моей системы для создания он-лайн документации.

Система представляет собой комплекс на php, который можно использовать без веб-сервера через командную строку, или в виде сайта под управлением apache. Исходники документации хранятся в текстовых файлах и могут быть помещены в svn. Документация экспортируется в полностью статический html, для размещения на сайте и для скачивания. Имеется экспорт в файл справки chm

Читать дальше →
Total votes 12: ↑10 and ↓2 +8
Views 131
Comments 3

BullDoc 0.31 Released

Lumber room
Сделан экспорт в монолитный html-файл и добавлена поддержка кодировки utf-8 для русского языка.

О программе: BullDoc — это система для создания документации. Представляет собой комплекс на php, который можно использовать без веб-сервера через командную строку, или в виде сайта под управлением apache. Исходники документации хранятся в текстовых файлах и могут быть помещены в svn. Документация экспортируется в полностью статический html(один файл на одну страницу или один монолитный файл), для размещения на сайте и для скачивания. Имеется экспорт в файл справки chm.


Читать дальше →
Total votes 2: ↑2 and ↓0 +2
Views 183
Comments 11

XML документация в C#

.NET *
Приветствую, хабра-дотнетчики!
Сегодня речь пойдет об одной интересной и полезной возможности языка С#, которая поможет нам в документировании кода. Она называется «XML документация» или «Документирующие комментарии XML». Это такие специальные теги XML, которые содержаться в комментариях и описывают свойства или методы в конкретном файле. Так вот, есть по крайней мере три веских причины, почему всегда следует заполнять XML комментарии.

Читать дальше →
Total votes 52: ↑45 and ↓7 +38
Views 62K
Comments 73

BullDoc 1.0

Lumber room
Проект дозрел до 1.0 :)

Нововведений почти нет, только фиксы.

Единственное нововведение — картинки обложек на книжной полке

Написал английский перевод на всякий случай, однако прошли те времена, когда можно было рассказать про свою программу на sitepoint. Теперь такое удаляют за self promotion.

О программе: BullDoc — это система для создания документации. Представляет собой комплекс на php, который можно использовать без веб-сервера через командную строку, или в виде сайта под управлением apache. Исходники документации хранятся в текстовых файлах и могут быть помещены в svn. Документация экспортируется в полностью статический html(один файл на одну страницу или один монолитный файл), для размещения на сайте и для скачивания. Имеется экспорт в файл справки chm.

Стандартные реквизиты:
www.bulldoc.ru
Статья на хабре про программу
FAQ
Пример шаг-за-шагом
Документация
Скачать
Total votes 5: ↑4 and ↓1 +3
Views 320
Comments 0

Русскоязычный javascript reference

Lumber room
Возникла идея написать русскоязычный референс по современному жавоскрипту. В качестве платформы выбрал Sphinx. Ещё пару дней поковыряю, чтобы оценить трудозатраты и решусь окончательно.

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

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

morg.regolit.com/js-ref/core/array.html

Ну, и самая мажорная цель — совместная работа над материалом. Хостинг есть, mercurial уже настроен. Однако объём работы титанический, один из самых геморройных моментов — определение межбраузерной совместимости. Стоит ли вообще игра свеч?

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

П.П.С.
Пока в персональном блоге, поскольку идея пришла в голову буквально несколько часов назад и ещё толком не оформилась.
Total votes 9: ↑8 and ↓1 +7
Views 198
Comments 12

Русская документация по PHP?

PHP *
Зашёл сегодня на официальный сайт, и не нашёл там русской документации в онлайне…
На странице загрузки русского также нет…

Диверсия? Или давно никто не обновлял, они и потёрли?

P.S.: В настройках сайта русского языка также нет…
Total votes 16: ↑7 and ↓9 -2
Views 2.5K
Comments 14

Что такое хороший мануал к ПО?

MCNtelecom corporate blog
Хотелось столько всего рассказать, столько всего написать, что теряешься от созерцания горизонтов тем, мыслей, соображений.

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

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

Но это были одни из основных ожидаемых направлений деятельности.

Не думали не гадали мы, и, прямо таки, никак не ожидали мы, что продукт станет ожидать от нас координального обновления справочного материала.

Сделать продукт не просто, но написать к нему грамотный мануал не легче.
Возникло много интересных идей и рациональных предложений, но хотелось бы спросить у хабролюдей, что для них является показателем хорошего мануала к ПО?
Total votes 6: ↑5 and ↓1 +4
Views 3K
Comments 12

Создание документации в .NET

.NET *
Open notebookКачественная документация – неотъемлемая часть успешного программного продукта. Создание полного и понятного описания всех функций и возможностей программы и программного компонента требует немало сил и терпения. В данной статье я рассмотрю некоторые практические аспекты создания документации для .NET компонентов.

Предположим, что у нас готова или почти готова некоторая .NET библиотека для разработчиков (они же конечные пользователи). API библиотеки безупречен, количество багов впечатляюще мало, да и вообще это не библиотека, а просто кладезь совершенного кода. Дело за малым – объяснить пользователям, как работать с этим замечательным продуктом.

Есть разные подходы к написанию документации. Некоторые команды предпочитают начинать создание документации в момент начала создания продукта. Другие откладывают написание мануалов на окончание работ. В некоторых командах документацию пишут специальные люди, которые ходят от разработчика к разработчику и от менеджера к менеджеру, аккумулируя знания о продукте. Во многих небольших командах таких специальных людей нет, а потому документацию часто пишет разработчик или разработчики. Кто-то использует сторонние средства вроде Help & Manual, в которых, как в заправском текстовом редакторе, можно создавать очень сложную верстку и на выходе получать документацию в многообразии форматов. Многие используют другой подход, широко пропагандируемый в последнее время – написание документации прямо в коде программы/библиотеки.

Читать дальше →
Total votes 95: ↑82 and ↓13 +69
Views 46K
Comments 29

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

MongoDB *
Буквально сегодня увидел у себя в Facebook сообщение о том, что команда из 10gen, занимающаяся разработкой, ставшей причиной долгих и упорных споров, MongoDB, набирает добровольцев для перевода актуальной документации к этой БД.

Вот полный список языков, на которые планируется перевод:
  • Chinese
  • French
  • German
  • Hebrew
  • Hungarian
  • Indonesian
  • Italian
  • Japanese
  • Korean
  • Portuguese
  • Russian
  • Serbian
  • Spanish
  • Swedish
  • Vietnamese

Читать дальше →
Total votes 33: ↑32 and ↓1 +31
Views 6.6K
Comments 3

Python-неизвестный

Python *
На Хабре уже есть несколько статей\переводов, в которых рассказывается о неизвестных фичах\тонкостях\возможностях Пайтона. Я буду пытаться не повторять их, а дополнять, но если уж так случилось, что вы это уже где-то видели — не огорчайтесь. Я уверен, что найдется что-то интересное и для вас.
Читать дальше →
Total votes 144: ↑140 and ↓4 +136
Views 23K
Comments 51

Команде переводчиков документации PHP требуется помощь

PHP *
Upd: Для нетерпеливых: пошаговые инструкции по созданию переводов.

Русская документация PHP


Добрый день Хабрасообщество!
Как многим известно, вот уже долгое время на php.net нет русской версии документации PHP. Это не значит, что работа по переводу была прекращена, а результаты этой работы пропали.
Дело в том, что перевод документации — добровольное дело, и добровольцев, скажем так, не много. Один-два человека старались удержать перевод на плаву, но все равно в конце концов документация устарела и скорее вводила в заблуждение тех, кто ей пользовался, нежели помогала в освоении языка. Где-то в 2008 г. в команде переводчиков никого не осталось, потом документация устарела настолько, что процесс сборки (куда входит синхронизация с английской версией) сломался и русский мануал исчез с официального сайта до «лучших времен». Медленное и мучительное возрождение документации началось в октябре 2010 г., но с тех пор оно с каждым днем набирает обороты.
Читать дальше →
Total votes 87: ↑76 and ↓11 +65
Views 2.5K
Comments 53

Онлайн генератор документации для Node.JS проектов

JavaScript *Node.JS *
Документация — одна из самых важных составляющих любого проекта, особенно если этот проект с открытым кодом, который будут читать другие люди. Чтобы сделать мир opensource чуточку лучше, я попытался собрать свои знания в области организации модулей nodejs проектов и сделать такой инструмент как Makedoc!. Ремарка для адептов ruby: это почти то же, что и rdoc.info для руби.

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

В кратце шаблон использования такой: идем на jsdoc.info/[githubusername]/[projectname] и видим готовую документацию по проекту. Либо идем на jsdoc.info/[githubusername] и получаем список проектов для которых можно сгенерировать документацию.

За деталями реализации прошу под кат.
Читать дальше →
Total votes 20: ↑19 and ↓1 +18
Views 5K
Comments 34

J: программирование на смайликах

Abnormal programming *Functional Programming *
Язык J многими, в том числе и на хабре, считается write-only language (что, в общем-то, неправда) или программированием через регэкспы. Важно помнить, что J — это ASCII-версия математической нотации Айверсона, лежащей в основе APL. Точно так же, как невозможно прочесть Хиндли-Милнера, не зная математической нотации, код вроде value =: [:(]`{.@.([:1&=#))[:,[:>[((([:<[)=[:{.])#[:{:])[:>] не может быть понятен человеку, незнакомому хотя бы со словарём языка.

Под катом небольшая подборка учебников и туториалов по теме для заинтересовавшихся. (Внимание: все ресурсы на английском языке)
Читать дальше →
Total votes 30: ↑19 and ↓11 +8
Views 9.8K
Comments 8

И ещё пару слов о SandCastle, TFS и магии…

Programming *.NET *Visual Studio *
Sandbox
По мотивам только-только проскочившей публикации «Sandcastle и SHFB» решил поделиться своими болями и печалями, а также и success-story при работе с этим продуктом.

В тексте не будет скриншотов с подписями "нажмите кнопку ДОБАВИТЬ" и описания настроек/плагинов.
В тексте будет описание процесса реализации конкретного кейса: сборки документации SHFB в TFS.
Читать дальше →
Total votes 9: ↑9 and ↓0 +9
Views 4.3K
Comments 2

Автоматическая генерация API doc через Аннотации или как прийти к документированию API

PHP *Symfony *
Sandbox
Перед написанием стать попытался найти что-то подобное, и, возможно, в силу каких-то обстоятельств не нашел. Решил изложить свое видение данного вопроса.

Откуда взялась идея? За последние несколько лет я сменил 3-4 компании, в которых мне доставалась мягко говоря лапша, толстенные контроллеры и минимум аннотаций. С чем именно связать отсутствие аннотаций — сказать сложно, возможно, это банальная лень или не знание того, что аннотации позволяют описывать больше, чем просто входящие параметры для классов/методов. А когда это начинает касаться API-контроллеров, то тут вообще весело, прикрутить FosRestBundle не проблема (я сейчас про более ленивый вариант, чем написание всего и вся самому ручками, хотя, как показывает практика — бандл проще).
Читать дальше →
Total votes 6: ↑4 and ↓2 +2
Views 17K
Comments 18