azproduction14 янв 2011 в 10:42

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

3 мин

29K

JavaScript *

Перевод

+28

Комментарии 18

khamukhin 14 янв 2011 в 13:03

Немного сбило с толку:

Проект GitHub имеет wiki, которая генерируется движком Git.

Насколько я понял, у GitHub своя wiki-система, которая основана опять же на Git. В этой wiki хранят версии документов в Git, используют историю Git, git-diff и т.д.

azproduction 14 янв 2011 в 13:15

Спасибо, исправлю.

kmike 14 янв 2011 в 13:50

Вот тут хорошие аргументы по поводу того, чем плоха автоматически сгенерированная из исходников (JSDoc, Javadoc, RDoc и т.д.) документация:
jacobian.org/writing/great-documentation/what-to-write/

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

Хотя к инструментам вроде Docco можно присмотреться. Еще рано говорить, хорошая это идея или нет, но определенная логика в том, чтобы делать документацию в стиле Docco, похоже, есть.

flexoid 14 янв 2011 в 18:42

восновном — > в основном

flexoid 17 янв 2011 в 09:34

В чем дело? Поправил ошибку, зачем минусы?

Finesse 8 сен 2015 в 04:08

Комментарии для обсуждения содержимого статьи. О грамматических ошибках принята писать в л/с.

ozonar 15 сен 2016 в 11:00

Мудрый комментарий даже спустя пять лет будет мудрым

AgentSmith 14 янв 2011 в 18:44

Забавно, что свою докементацию я тоже писал, опираясь на jQuery/Ajax. Ещё как вариант рассматривал API Sendspace: www.sendspace.com/dev_method.html
Описание API фейсбука я отверг как сложное

mythmaker 14 янв 2011 в 19:25

Забыли пример документации для ExtJS, сделанный на ext-doc

azproduction 14 янв 2011 в 22:03

Все в нем хорошо, но з

azproduction 14 янв 2011 в 22:04

сорвалось… занимает при первой загрузке он около мегабайта, если предоставлять документацию открыто, то слишком грузно.

alexsrdk 14 янв 2011 в 19:29

Документация jQuery располагается по адресу docs.jquery.com

Иногда удобнее пользоваться непосредственно jQuery API

Insa88 14 янв 2011 в 21:08

«Даже если ваш проект с закрытым исходным кодом» — на хуй такие проекты! И документация не поможет!!!

Insa88 14 янв 2011 в 21:55

Раз пошли непонимания, поясни свою мысль. Я изобрел новое колесо и все знают его устройство, и какой-то умник его через полгода усовершенствовал и покатил быстрее. Он молодец — а я дурак, если я пол года нихера не делал, чтобы это вращалось еще быстрее. ПРИВЕТ УМНИКАМ И ИХ МИНУСАМ!!! 21 век! мы тупеем и жадность растет в прогрессии!!!