Что мне нужно охватить в моей документации? - PullRequest
Новая
       32

Что мне нужно охватить в моей документации?

0 голосов
/ 24 ноября 2011

Я пишу собственную документацию для небольшой библиотеки ActionScript 3.

Я стараюсь максимально приблизиться к макету и содержимому Adobe Livedocs, поканемного очистив его.

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

Есть ли что-нибудь, что вы хотели бы иметь в документации?Есть ли в большинстве документов что-то, что вы считаете несущественным?

Вот что я получил до сих пор: https://projectavian.com/docs/zephyr/#/entity

Вот некоторые вещи, которые я пытался охватить:

  1. Простые прямые ссылки на разделы документации.т. е. /#/class.propertyOrMethod, как указано выше.
  2. В верхней части страницы аккуратные таблицы с кратким описанием каждого свойства, метода, константы или любых других соответствующих скобок, присутствующих в классе.информация, относящаяся к каждому свойству или методу, по которой можно перейти непосредственно по URL-адресу на шаге 1. Щелчок по соответствующему тексту в таблицах вверху страницы также приведет к ссылке здесь.
  3. Аккуратный макет для методааргументы с краткими объяснениями о каждом.

1 Ответ

1 голос
/ 24 ноября 2011

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

некоторые хорошо документированные классы AS, которые я знаю:

TweenMax @ http://www.greensock.com/as/docs/tween/com/greensock/TweenMax.html BulkLoader @ http://media.stimuli.com.br/projects/bulk-loader/docs/ CASA Lib @ http://as3.casalib.org/docs/

Вы можете просматривать их для вдохновения / понимания в очень тонких документах класса Action Script. Каждый из них прошел несколько версий и выдержал испытание временем.

...