azproduction Jan 14 2011 at 13:42

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

3 min

29K

JavaScript*

Translation

+29

Comments 18

khamukhin Jan 14 2011 at 16:03

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

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

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

azproduction Jan 14 2011 at 16:15

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

kmike Jan 14 2011 at 16:50

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

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

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

flexoid Jan 14 2011 at 21:42

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

-3

flexoid Jan 17 2011 at 12:34

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

Finesse Sep 8 2015 at 07:08

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

ozonar Sep 15 2016 at 14:00

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

AgentSmith Jan 14 2011 at 21:44

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

mythmaker Jan 14 2011 at 22:25

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

azproduction Jan 15 2011 at 01:03

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

azproduction Jan 15 2011 at 01:04

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

alexsrdk Jan 14 2011 at 22:29

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

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

Insa88 Jan 15 2011 at 00:08

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

-4

Insa88 Jan 15 2011 at 00:55

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

-1