Разработка технической документации и технические писатели Технические писатели и разработка технической документации технические писатели в Телеграм 

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1
Ответить
RSS
Техническая документация на ПО, Нужна помощь
 
Здравствуйте. Так уж получилось, что меня попросили составить техническую документацию, а я в этом вообще практически не разбираюсь, но уже достаточно много прочла и ознакомилась с информацией по данной теме.
Мне дали несколько тестовых файлов: smoke-test, limit и basic (файлы в разрешении features). Вроде бы все просто, но никак не могу понять, как писать эту документацию, не могли бы вы мне помочь хотя бы сделать набросок по этой документации, это очень сильно мне поможет.

Содержание файла basic.feature вот такое:
Код
# vim: set tabstop=2 shiftwidth=2 softtabstop=2 et:
Feature: allocate and deallocate resources
  Users can ask the service to allocate a resource, or deallocate it if it is
  not needed anymore.
  Resources are allocated by the user name and deallocated by the resource name.
  User can request the list of all the allocated and deallocated resources,
  or just the list of allocated resources by him only.
  The service provides an ability to reset its state so that all the resources
  become deallocated.
 
  Example:
  $ curl http://resm.tld/reset
  $ curl http://resm.tld/allocate/bob
  resource#1
  $ curl http://resm.tld/list
  {"allocated":{"resource#1":"bob"},"deallocated":[...]}
  $ curl http://resm.tld/list/bob
  ["resource#1"]
 
Scenario: list resources before allocation
  Given an empty pool
  When a user "alice" lists resources
  Then status code should be 200
  And the resources list should be empty
 
Scenario: list all resources before allocation
  Given an empty pool
  When a user lists all resources
  Then status code should be 200
  And the allocated resources list should be empty
 
Scenario: deallocate resource before allocation
  Given an empty pool
  When a user deallocates resource "resource"
  Then status code should be 404
  And an error message should be "Not allocated"
 
Scenario: allocate resource
  Given an empty pool
  When a user "alice" allocates resource
  Then status code should be 201
  And the response should be not empty
 
Scenario: list resources after allocation
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user "alice" lists resources
  Then status code should be 200
  And the resources list should be
    | resource |
    | %a%      |
 
Scenario: list all resources after allocation
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user lists all resources
  Then status code should be 200
  And the allocated resources list should be
    | user  | resource |
    | alice | %a%      |
 
Scenario: deallocate resource after allocation
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user deallocates resource "%a%"
  Then status code should be 204
  And the response should be empty
 
Scenario: duplicate allocate resource
  Given an empty pool
  When a user "alice" allocates resource
  And a user "alice" allocates resource
  Then status code should be 201
  And the response should be not empty
 
Scenario: list resources after duplicate allocation
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user "alice" allocates resource "b"
  And a user "alice" lists resources
  Then status code should be 200
  And the resources list should be
    | resource |
    | %a%      |
    | %b%      |
 
Scenario: list resources after deallocation
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user deallocates resource "%a%"
  And a user "alice" lists resources
  Then status code should be 200
  And the resources list should be empty
 
Scenario: duplicate deallocate resource after allocation
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user deallocates resource "%a%"
  And a user deallocates resource "%a%"
  Then status code should be 404
  And an error message should be "Not allocated"
 
Scenario: allocate resource after deallocation
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user deallocates resource "%a%"
  And a user "alice" allocates resource
  Then status code should be 201
  And the response should be not empty
 
Scenario: list only own resources
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user "bob" allocates resource "b"
  And a user "alice" allocates resource "c"
  And a user "alice" lists resources
  Then status code should be 200
  And the resources list should be
    | resource |
    | %a%      |
    | %c%      |
 
Scenario: list all resources for several users
  Given an empty pool
  When a user "alice" allocates resource "a"
  And a user "bob" allocates resource "b"
  And a user "alice" allocates resource "c"
  And a user lists all resources
  Then status code should be 200
  And the allocated resources list should be
    | user  | resource |
    | alice | %a%      |
    | bob   | %b%      |
    | alice | %c%      |
 
Svetlana, я не понял, что вам нужно). Добивайтесь от Заказчика, какую документацию и для кого вам нужно ее написать. Вы привели, как я понял,  какую-то техническую информацию по ПО и что вам нужно сделать то? Описать как она работает? Для кого? Для пользователя? Для разработчиков? Написать ТЗ? Написать Руководство пользователя? Программа вообще существует? Выясните в первую очередь эти вопросы.  
 
Цитата
writer написал:
Svetlana , я не понял, что вам нужно). Добивайтесь от Заказчика, какую документацию и для кого вам нужно ее написать. Вы привели, как я понял,  какую-то техническую информацию по ПО и что вам нужно сделать то? Описать как она работает? Для кого? Для пользователя? Для разработчиков? Написать ТЗ? Написать Руководство пользователя? Программа вообще существует? Выясните в первую очередь эти вопросы.
Программа пока на стадии разработки. На основе этих тестов надо описать как она работает и написать руководство пользователя))
 
Светлана, а вы лично работали с этой программой (веб-сервисом)? Умеете ее устанавливать и настраивать?

В другом сообщении вы писали, что требуется написать "инструкции по установке и настройке, ответы на часто задаваемые вопросы"

Надеюсь, вы понимаете, что установка и настройка веб-сервиса, и использование веб-сервиса — это разные функции, которые выполняются разными людьми, которые, возможно не знакомы и находятся во многих тысячах километров друг от друга? Пользователь обычно не занимается установкой и настройкой сервиса, а установщик (администратор) - не использует сервис, кроме целей проверки его работоспособности, оценки производительности и т.п. (и даже эти действия могут выполнять другие люди). Поэтому установку/настройку и использование веб-сервиса принято описывать в разных документах, а не в одном "руководстве пользователя".
Изменено: Виктор Фигурнов - 20.05.2015 12:40:44
Страницы: 1
Ответить
Читают тему
Форма ответов
 
Текст сообщения*
Загрузить файл или картинкуПеретащить с помощью Drag'n'drop
Перетащите файлы
Ничего не найдено
Загрузить файлы
Отправить Отменить