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

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1 2 3 След.
RSS
Классификация технической документации, В этой теме рассматриваем какие виды технической документации существуют
 
Внимание...вопрос!
Какие классификации технической документации вы знаете? Или скорее всего, копнем глубже, и выясним какие виды классификаций технической документации существуют на самом деле, давайте докопаемся и составим полный список.
 
Долго придется составлять. Только для документации по информационным продуктам стандарт ISO/IEC/IEEE 15289 "Systems and software engineering — Content of life-cycle information products (documentation)" перечисляет 91 вид технических документов.
 
Цитата
Виктор Фигурнов пишет:
Долго придется составлять. Только для документации по информационным продуктам стандарт ISO/IEC/IEEE 15289 "Systems and software engineering — Content of life-cycle information products (documentation)" перечисляет 91 вид технических документов.
ну тогда, наиболее востребованные у нас, хотя я бы пееречислил все, может имеет смысл это в wiki сделать
 
Приведу пример классификации пользовательской документации. На самом верхнем уровне считаю целесообразно классифицировать по уровню пользователя (для начинающих и экспертных).
Для начинающих пользователей должны разрабатываться следующие виды документов: глоссарий, быстрый старт, туториалы, руководство пользователя. Для опытных пользователей:  глоссарий, справочник, руководство пользователя. Далее для каждого вида документов определяется свой формат.
Если документация разрабатывается по ГОСТам, то соответственно классификация должна им соответствовать.
techwriter.ru.com
 
Цитата
techwriter пишет:
Приведу пример классификации пользовательской документации.
Спасибо!
 
Цитата
techwriter пишет:
Приведу пример классификации пользовательской документации.
Пользовательская документация относится к типу Эксплуатационная. А эксплуатационная входит в техническую.

Если рассматривать техническую документацию, касаемо тех.писателей, я бы выделил тра пункта.
1. Эксплуатационная (руководства всех видов и для всех аудиторий, справки, FAQ)
2. Проектная (ТЗ, технические требования, спецификации)
3. Технологическая (регламенты, методики, стандарты)

Еще есть ПМИ и документация по разработке ПО, ее пока не знаю куда отнести.
 
Цитата
ADVANCED пишет:
Цитата
techwriter пишет:
Приведу пример классификации пользовательской документации.
Пользовательская документация относится к типу Эксплуатационная. А эксплуатационная входит в техническую.

Если рассматривать техническую документацию, касаемо тех.писателей, я бы выделил тра пункта.
1. Эксплуатационная (руководства всех видов и для всех аудиторий, справки, FAQ)
2. Проектная (ТЗ, технические требования, спецификации)
3. Технологическая (регламенты, методики, стандарты)

Еще есть ПМИ и документация по разработке ПО, ее пока не знаю куда отнести.
Если я не привязана к каким-либо стандартам, то я упрощаю и называю всю документацию пользовательской. Повторюсь, дальше делю по уровням пользователей.
Если придерживаюсь стандартов, то и классификация строго по ним.
techwriter.ru.com
 
Цитата
techwriter пишет:
Если я не привязана к каким-либо стандартам, то я упрощаю и называю всю документацию пользовательской
Но она не вся пользовательская. Есть ТЗ, есть документация разработчиков и т.д.
Описание форматов или протоколов, которые не входят в ТЗ не может быть пользовательской документацией по определению. Само ТЗ также не может быть пользовательским :)  
 
Цитата
ADVANCED пишет:
Если рассматривать техническую документацию, касаемо тех.писателей, я бы выделил тра пункта.
1. Эксплуатационная (руководства всех видов и для всех аудиторий, справки, FAQ)
2. Проектная (ТЗ, технические требования, спецификации)
3. Технологическая (регламенты, методики, стандарты)
Вообще документация бывает нормативно-техническая, конструкторская, проектная, технологическая, эксплуатационная, программная, инструктивно-методическая и другая.

Стандарт ISO/IEC/IEEE 15289:2011 выделяет 7 групп видов документов относящихся к информационным технологиям - описание, план, политика, процедура, отчет, запрос и спецификация. В этих группах он перечисляет 91 видов документов.

Еще можно делить документацию по тому, к какому этапу жизненного цикла систем, программ, услуг она относится (стандарты ISO 15288:2008, 12207:2008, и 20000-1,2:2011 соответственно).
 
Цитата
ADVANCED пишет:
Цитата
techwriter пишет:
Если я не привязана к каким-либо стандартам, то я упрощаю и называю всю документацию пользовательской
Но она не вся пользовательская. Есть ТЗ, есть документация разработчиков и т.д.
Описание форматов или протоколов, которые не входят в ТЗ не может быть пользовательской документацией по определению. Само ТЗ также не может быть пользовательским  :)
Документация разработчиков - тоже пользовательская документация. Чем разработчик не пользователь? Просто другой уровень пользователя. И разработчик тоже может быть начинающим, кстати. Для начинающих разработчиков тоже, по моему мнению, должна быть отдельная документация.
Ты конечному пользователю ТЗ даешь? Конечный пользователь = пользователь, который работает с готовым продуктом. Конечному пользователю вообще проектная документация неинтересна. У него есть продукт, с которым он работает - данность, и документация, которая помогает ему с ним работать.
ТЗ относится к проектной документации, и никак иначе. ТЗ отражает требования к системе. И не всегда может существовать в конторе, и не всегда разрабатывается техническим писателем. По уму, ТЗ должно разрабатываться бизнес-аналитиком и системным аналитиком. Если документация предоставляется заказчику в соответствии с ГОСТ, то и классификация всей документации будет по ГОСТ, о чем я выше написала. В этом случае вся документация будет в общем случае классифицироваться по стадиям создания системы, определенным в стандарте и никак по-другому.
techwriter.ru.com
 
Цитата
techwriter пишет:
Документация разработчиков - тоже пользовательская документация. Чем разработчик не пользователь?
Как правило, разработчик - не пользователь. Разработчик тампакса может быть мужчиной, например.  :)

Согласно ГОСТ Р ИСО/МЭК 12207-2010, п. 4.53, Пользователь - это лицо или группа лиц, извлекающих пользу из системы в процессе ее применения.
Разработчик может вообще никогда не использовать систему для извлечения пользы, т.е. для каких-то практических задач.
 
Цитата
Виктор Фигурнов пишет:
Цитата
techwriter пишет:
Документация разработчиков - тоже пользовательская документация. Чем разработчик не пользователь?
Как правило, разработчик - не пользователь. Разработчик тампакса может быть мужчиной, например.  :)  

Согласно ГОСТ Р ИСО/МЭК 12207-2010, п. 4.53, Пользователь - это лицо или группа лиц, извлекающих пользу из системы в процессе ее применения.
Разработчик может вообще никогда не использовать систему для извлечения пользы, т.е. для каких-то практических задач
А кто ж он?
techwriter.ru.com
 
Виктор, не соглашусь с Вами. Если есть платформа и прикладные решения на ее основе, то вполне реальна еще одна прослойка пользователей - разработчики.

Хотя относительно платформы - они будут считаться "пользователями".

Но это всё одна классификация - по типу адресата документации.
Изменено: Elanor - 19.08.2014 14:29:03
 
Цитата
techwriter пишет
Цитата
Виктор Фигурнов пишет:
Как правило, разработчик - не пользователь. Разработчик тампакса может быть мужчиной, например.   :)  
Цитата
А кто ж он?
Мало ли кто. Программист, дизайнер, художник, менеджер, и т.д.

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

А в эту игру он не играет. Вообще. Значит, он не пользователь.
Изменено: Виктор Фигурнов - 19.08.2014 16:55:56
 
На примере игры:
Если компания создала движок для создания компьютерных игр (был такой RPG Maker), то у этого движка два уровней пользователей: те, кто на нем создают игры ("разработчики" по сути), и те, кто в них играют (конечные пользователи - игроки).
Изменено: Elanor - 19.08.2014 17:19:39
 
Цитата
Виктор Фигурнов пишет:
Цитата
techwriter пишет
Цитата
Виктор Фигурнов пишет:
Как правило, разработчик - не пользователь. Разработчик тампакса может быть мужчиной, например.  :)  
Цитата
А кто ж он?
Мало ли кто. Программист, дизайнер, художник, менеджер, и т.д.

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

А в эту игру он не играет. Вообще. Значит, он не пользователь.
Это разные виды пользователей. Если вы утверждаете, что такого вида пользователя как разработчик не существует, то и документации для них вы не выделяется как класс. Вы что включаете в документацию разработчика?
techwriter.ru.com
 
Цитата
Elanor пишет:
На примере игры:
Если компания создала движок для создания компьютерных игр (был такой RPG Maker), то у этого движка два уровней пользователей: те, кто на нем создают игры ("разработчики" по сути), и те, кто в них играют (конечные пользователи - игроки).
Вот-вот. Я о том же :))) Есть системы, у которых есть фронт- и бэк-офис. Бэк-офис может быть как для администраторов, так и для разработчиков. Если бэк-офис существует, то и пользовательская документация по нему должна быть.
techwriter.ru.com
 
Разработчик может быть пользователем только когда есть чем пользоваться. Если системный архитектор только создает структуру ПО и продумывает связи на этапе изучения ТЗ. то пользователей программы не может существовать в природе, независимо кто они. Они только на бумаге фигурируют.
 
ADVANCED,
Фирма ХYZ может разрабатывать свою мегаплатформу, на которой разработчики-пользователи могут создавать свои "решения", и продавать их конечным пользователям.

ПО по сути может быть использовано для создания программных продуктов. И тогда речь о разработчиках, как пользователях этого самого ПО (платформы).
 
Цитата
Elanor пишет:
ADVANCED,
Фирма ХYZ может разрабатывать свою мегаплатформу, на которой разработчики-пользователи могут создавать свои "решения", и продавать их конечным пользователям.

ПО по сути может быть использовано для создания программных продуктов. И тогда речь о разработчиках, как пользователях этого самого ПО (платформы).
Вы путаете роли.
Разработчик ДРУГОГО ПО может быть пользователем "мегаплатформы". Для него будет предназначена пользовательская документация "как разрабатывать ПО на базе "мегаплатформы".

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

И как раз разработчику стороннего ДРУГОГО ПО будет доступна малая часть мощностей и ресурсов "мегаплатформы", которые ему выделены согласно тарифам/договорам как конечному пользователю и предоставлена документация по их эксплуатации.



Вот еще пример:
ТЗ на изготовление комплекта узлов и агрегатов, деталей и комплектующих для автомобиля - это проектная документация для инженеров, сталеваров, резиномесов, стеклодувов и кто там еще участвует не знаю. Ее конечно можно посмотреть потом, но толку от нее мало будет, т.к. все будет изготовлено. На переделку нужно будет другое ТЗ. И все это не касается конечного потребителя.
Технология сборки деталей автомобиля в автоцехе - один документ. Ремонт этого же автомобиля в гараже подручными средствами - другой, эксплуатация этого же автомобиля - третий. замена двигателя в сервисе - четвертый. замена лампы - пятый.
 
Цитата
Elanor пишет:
ADVANCED,
Фирма ХYZ может разрабатывать свою мегаплатформу, на которой разработчики-пользователи могут создавать свои "решения", и продавать их конечным пользователям.

ПО по сути может быть использовано для создания программных продуктов. И тогда речь о разработчиках, как пользователях этого самого ПО (платформы).
При создании документации в MS Word вы можете посмотреть справку по Word. Для вас он - конечный продукт. Но его тоже кто-то разрабатывал.

На него кроме справки есть ТЗ, требования к тестированию и т.п. Это проектная документация и ее наверное нет в открытом доступе для всех пользователей Word.
 
Я не про продукт типа Ворда.
Я про продукт типа платформы, например "1С:Предприятие"
У нее есть документация на пользователя, разработчика, администратора.

Потому что платформа - это не все. Важно - прикладное решение, созданное на платформе.

Прикладное решение наваять может хоть Вася Пупкин - Руководство РАЗРАБОТЧИКА написано для него.


Но для разрабов из 1Са - Вася Пупкин такой же пользователь, только другого уровня.


А для бухгалтерши тети Любы (конечный пользователь) - Вася тоже разработчик.


Вот такие пироги с котятами.
Все мои опусы были к утверждению о том, что "разработчик не пользователь". И сводились к тому, что пользователь продукта может быть "не конечным" пользователем, а именно - разработчиком.
Изменено: Elanor - 20.08.2014 14:21:31
 
Цитата
Elanor пишет:
пользователь продукта может быть "не конечным" пользователем, а именно - разработчиком.
Разработчиком иного продукта на базе первого - да. Разработчиком этого же продукта - не всегда, только когда продукт уже существует. Если продукта не существует, как можно быть его пользователем?

Цитата
Elanor пишет:
Я про продукт типа платформы, например "1С:Предприятие"
У нее есть документация на пользователя, разработчика , администратора.
Это пользовательская документация. Она относится к эксплуатационной.


Цитата
techwriter пишет:
Ты конечному пользователю ТЗ даешь? Конечный пользователь = пользователь, который работает с готовым продуктом. Конечному пользователю вообще проектная документация неинтересна. У него есть продукт, с которым он работает - данность, и документация, которая помогает ему с ним работать.
Нет не даю. Разработчику (если он УЖЕ разработал 1С определенной версии), выступающий в роли пользователя (тоже самой версии) ТЗ будет как "козе баян".
ТЗ - проектная документация, существовавшая на этапе создания ПО. т.е. только для разработчика, который пишет код и тестирует ПО, которое официально не существует. Он не может им пользоваться.  
 
Цитата
Elanor пишет:
А для бухгалтерши тети Любы (конечный пользователь) - Вася тоже разработчик.
Мнение тети Любы не следует считать правильным в определении категорий документации. По ее мнению Вася и администратор и программист и хакер и вообще "я не знаю чем он занимается".

Все перемешали. Продуктом в данном случае является платформа и оболочка 1С.

1. Для тех, кто с нуля начнет разрабатывать 1С, его API, шины, библиотеки - будет только ТЗ с описанием как это сделать. Участники разработки ( в т.ч. писатели) должны будут создать документацию по платформе, API, шинам, библиотекам, форматам, железкам и т.п.
2. Для тех, кто захочет на базе платформы (1) написать новые приложения - документация будет классифицироваться заново: проектная (ТЗ на разработку приложения на базе 1С), эксплуатационная (руководство разработчика, пользователя, админа, дизайнера, предоставляемая разработчиками платформы (1) и писателями после завершения разработки в п.1) и т.д.
3. Для тех кто захочет на базе приложения (2), сделанного на базе платформы создать новое приложение также будет проектная (ТЗ на разработку приложения, сделанного на базе приложения, созданного на базе платформы 1С) , эксплуатационная (руководство разработчика, пользователя, админа, дизайнера, предоставляемая разработчиками приложения (2) и писателями после завершения разработки в п.2) и т.д. .
Изменено: ADVANCED - 20.08.2014 15:44:50
 
Цитата
ADVANCED пишет:
Это пользовательская документация. Она относится к эксплуатационной.
"Эксплуатационная документация" - это ГОСТовый термин, ИМХО. Поэтому и имеет смысл называть документацию эксплуатационную, если она разрабатывается по требованиям ГОСТа. Если технический писатель свободен от ГОСТа и его требований к комплектованию и содержанию документации, то имеет смысл руководствоваться принципом разработки документации, ориентированной на пользователя (=пользовательская документация).
techwriter.ru.com
Страницы: 1 2 3 След.
Читают тему