Как написать документацию для приложения?

Question

[Demigodd]

Помогите расставить все по полочкам, что такое fspec, uses case, uses story, что из себя предстовляет вообще документация для приложения, это имеет отношение к unit test`ам.

Есть тестовое приложение To Do List на ноде и нужно написать документацию для него. Но непредстовляю как.

Можете скинуть материалы или пример проекта на гитхабе..
Заранее Спасибо.

Answer 1

[Alexej Simakov]

User story описывает цели которые могут быть достигнуты с помощью приложения. Они определяют пользу. Например, чтобы решить какую задачу выполнить сегодня, пользователь хочет определить самые приоритетные задачи. Польза приложения тут в помощи принятию решений по задачам. Тут нужно думать максимально с т.з конечного пользователя. Зачем он что-то делает и как продукт может помочь ему в этом.

Use cases будут включать в себя описания какие взаимодействия с приложением пользователь может произвести чтобы достичь своей цели. Например: Отсортировать по приоритету. Отфильтровать по тегам. И пр. По юзкейсам можно проверить, что приложение действительно предоставляет заявленные функции заявленным образом.

По юзкейсам можно проводить системное тестирование. Т.е. есть заявленный сценарий, работает он или нет.

Функциональная спецификация определяет детально устройство приложения, с подробным описанием всех технических "если", и "а вдруг".

По функциональной спецификации пишется реализация, и сам код приложения уже покрывается юнит-тестами.

Comments

[Demigodd]

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

[Alexej Simakov]

DEATH2298, а и нет никакой волшебной ссылки. А писал разьяснения по собственному опыту и сверял с источниками в интернете, чтобы убедиться, что моя интерпретация соответствует общепринятой. А так каждое понятие в отдельности разяснено в интернете, можно искать типа "use cases vs user stories". Можно искать "functional specification example document". Вы может быть удивитесь, но найти какие нибудь опенсорсные проекты которые прописывают себе спецификацию практически невозможно. Писать спецификацию, это очень дорого, и долго, для этого нужны специальные люди. И юзер сторис, даже если их "продают" в аджайле как легковесную замену фунциональной спецификации, не являются заменой, и хорошо их писать тоже, блин, надо уметь.
В аджайле просто обычно не пишут фунциональную спецификацию, а делают наброски, где затруднения и вопросы решают по мере их поступления в диалоге с заказчиком. И быстрее это или дешевле или гибче, это, конечно, трудно сказать. Но по опыту, никакая фунциональная спецификация не исключит в конце концов вопросов и неясностей. Так что что ты пишешь ее что нет. Так лучше наверно решать по ходу дела. Потому что в этом документе как таковом нет никакой ценности по окончании проекта, потом это мертвый артефакт.
С другой стороны в геймдизайне до сих пор используется диздок, это функциональная спецификация игры, и она очень подробна. Стоимость разработки игр очень большая, и спецификацию "заставляют" писать для того чтобы уже на этапе концепции отсеивать возможные будущие проблемы.

Answer 2

[Эдуард Тибет]

Тут все подробно и по полочкам. Как в универе: sce2.umkc.edu/BIT/burrise/pl