На Хабре уже есть несколько статей\переводов, в которых рассказывается о неизвестных фичах\тонкостях\возможностях Пайтона. Я буду пытаться не повторять их, а дополнять, но если уж так случилось, что вы это уже где-то видели — не огорчайтесь. Я уверен, что найдется что-то интересное и для вас.

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

Вот полный список языков, на которые планируется перевод:

• Chinese
• French
• German
• Hebrew
• Hungarian
• Indonesian
• Italian
• Japanese
• Korean
• Portuguese
• Russian
• Serbian
• Spanish
• Swedish
• Vietnamese

В этой статье хочется обратить внимание на важность двух аспектов разработки ПО.

• Если Вы делаете продукт, срок разработки которого больше одной недели — обязательно надо писать документацию.
• Любой документ может начать устаревать непосредственно в процессе своего написания и поэтому документацию писать бессмысленно

Как ни странно документация к некоторым проектам иногда таки пишется. Но не ко всем. И не всегда. Иногда это плохо, иногда нормально. А к некоторым проектам пишется очень много документации. Почему так происходит и как правильно?

UPD: В статье не рассматриваются такие документы как список требований или например договор с заказчиком о том сколько и когда будет заплачено. Подразумевается что полезность ТАКИХ документов если кому-то и не очевидна, то в любом случае это вопрос не для этой статьи. В основном тут речь о руководстве разработчика и родственных ему документах.

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

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

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

Привет друзья! Наткнулся на сайт с альтернативной документацией API jQuery — jQAPI. Сайт сделан в виде справочника, который максимально понятно и удобно передаёт информацию по использованию API jQuery.



— Вперёд к познанию!

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

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

P.S.: В настройках сайта русского языка также нет…

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

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

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

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

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

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

П.П.С.
Пока в персональном блоге, поскольку идея пришла в голову буквально несколько часов назад и ещё толком не оформилась.

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

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

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

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

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

Стандартные реквизиты:
www.bulldoc.ru
Статья на хабре про программу
FAQ
Пример шаг-за-шагом
Документация
Скачать

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