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

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1 2 След.
RSS
Предметная область и тех. писатель, Можно ли знать все?
 
Сегодня я была на одном собесе в компанию 1С, где меня загрузили вопросами по предметным областям (бухгалтерия, экономика и т.д.). Вопросы были из серии "На основании какого документа производится кладовщиком отгрузка продукции?"  %@@   И подведением итога, что я вообще ничего не понимаю и не понятно, что я могла писать без этих сакральных знаний.
Я в документации не новичок: работала и в медицине, и в "нефти", и на предприятиях-производителях. Но никто не требовал от меня знание предметной области. Получается, чтобы писать про медицинское ПО я должна была 7 лет в Меде отучиться, чтобы писать "со знанием дела"?  wall-smile   Иначе, "это простое описание кнопочек" (цитата чела из 1С)

А у Вас как с этим? Требуют знание предметной области? Или тех. писателю теперь надо в бухгалтерских законах разбираться, чтобы про проводки писать?
 
Мы работаем с охраной труда, и нормативку я изучала на испытательном сроке уже в компании. При приеме на работу никто этих знаний не требовал.
Работать надо не 12 часов, а головой.
 
Работодателю, конечно, в идеале хочется найти технического писателя, который разбирается в предметной области, но такого можно искать о-о-ох как долго. у 1С есть возможность поискать, штат техписов большой. Я работал и в банке,  в инф.безопасности, в торговле (ПО для учета) и в логистике, поэтому считаю, что знание предметной области желательно, но необязательно))
 
Считаю, что технический писатель должен разбираться в предметной области, понимать процессы и пр. Иначе он действительно сможет написать только документацию на уровне "нажал кнопку - получил такое-то окошко". Не всегда этого достаточно. Другой вопрос, что предметная область должна изучаться уже в процессе. На то мы и технические писатели, чтобы изучать предметную область, каким образом она автоматизирована с помощью продукта.
Короче, я бы так и ответила: "На то я и технический писатель, чтобы вникать в предметную область на этапе анализа поступающей ко мне информации перед началом разработки документации. Это всего лишь учетная система, а не ракета! Поэтому разберусь в минимально сжатые сроки при необходимости!"  
techwriter.ru.com
 
Цитата
techwriter пишет:
Другой вопрос, что предметная область должна изучаться уже в процессе. На то мы и технические писатели, чтобы изучать предметную область, каким образом она автоматизирована с помощью продукта.
Короче, я бы так и ответила: "На то я и технический писатель, чтобы вникать в предметную область на этапе анализа поступающей ко мне информации перед началом разработки документации. Это всего лишь учетная система, а не ракета! Поэтому разберусь в минимально сжатые сроки при необходимости!"
+100!! Это я и имел ввиду!!
 
Вот делюсь документиком, который подобрал в просторах интернета, а называется он так: "Профессиональный стандарт
«Технический писатель».

Скачать: pdf ~ 365 kb
 
Типы разрабатываемых документов  

с переводом. (2 страницы)

PS: тоже из интернета
 
Не спится? ;)
 
Цитата
ADVANCED пишет:
Не спится?
Такое бывает частенько из-за неустроенности в жизни... вот начинаешь задумываться-переживать и не спиться.
 
тоже не спал в это время но мы отходим от темы)
 
Цитата
убожетымой пишет:
Сегодня я была на одном собесе в компанию 1С, где меня загрузили вопросами по предметным областям (бухгалтерия, экономика и т.д.). Вопросы были из серии "На основании какого документа производится кладовщиком отгрузка продукции?" И подведением итога, что я вообще ничего не понимаю и не понятно, что я могла писать без этих сакральных знаний.
Я в документации не новичок: работала и в медицине, и в "нефти", и на предприятиях-производителях. Но никто не требовал от меня знание предметной области. Получается, чтобы писать про медицинское ПО я должна была 7 лет в Меде отучиться, чтобы писать "со знанием дела"? Иначе, "это простое описание кнопочек" (цитата чела из 1С)

А у Вас как с этим? Требуют знание предметной области? Или тех. писателю теперь надо в бухгалтерских законах разбираться, чтобы про проводки писать?
А как иначе? Без знания предметной области можно только про кнопки писать. О том, что видно на поверхности и понятно дилетанту. А получившуюся писанину потом специалист в предметной области должен внимательно прочесть и все ляпы выловить. Но это если важен качественный результат (у компании 1С именно такая ситуация), а не отписка для "галочки", что некий документ есть в наличии. Там, где нужна отписка, можно халтурить - писать не зная и не понимая предметной области, и лишь кое-как владея терминологией.
 
Цитата
Орлов Андрей пишет:
Типы разрабатываемых документов с переводом. (2 страницы)
Это к вопросу, заданному топик-стартеру на собеседовании, отношения не имеет. Техпис не пишет накладных, ведомостей на склад, лимитно-заборных книжек и прочих товарно-распорядительных документов, на основании которых кладовщики отпускают товары.

А типы документов в разных источниках указываются разные. Вот, например, классификация по международному стандарту ISO/IEC/IEEE 15289-2011 "Systems and software engineering — Content of life-cycle information products (documentation)":

Description

- Concept of operations
- Database design description
- Interface description
- Proposal
- Service catalog
- Software architecture description
- Software design description
- Software unit description
- System architecture description
- System element description

Plan

- Acceptance plan
- Acquisition plan
- Asset management plan
- Audit plan
- Capacity plan
- Configuration management plan and policy
- Development plan
- Disposal plan
- Domain engineering plan
- Improvement plan (process improvement plan, service improvement plan)
- Information management plan
- Information security plan
- Installation plan
- Integration plan (implementation plan)
- Maintenance plan
- Measurement plan
- Project management plan
- Quality management plan (quality assurance plan)
- Release plan
- Reuse plan
- Risk management policy and plan
- Service Availability and continuity plan
- Service management plan
- Training plan
- Validation plan
- Verification plan

Policy

- Configuration management plan and policy (change management policy, release policy)
- Improvement policy
- Information security policy
- Life cycle policy and procedure
- Quality management policy and procedure
- Risk management policy and plan

Procedure

− Audit procedure
− Capacity management procedure
− Configuration management procedure (change management procedure, release management procedure)
− Complaint procedure
− Implementation procedure
− Incident management procedure
− Life cycle policy and procedure
− Maintenance procedure
− Operational test procedure
− Problem management procedure
− Process assessment procedure
− Qualification test procedure
− Quality management policy and procedure
− Software unit test procedure
− Supplier management procedure
− Supplier selection procedure
− Training documentation
− User documentation

Report

− Acceptance review and testing report
− Audit acknowledgement report
− Audit report
− Configuration status report
− Evaluation report
− Incident report
− Installation report
− Integration and test report
− Monitoring and control report
− Problem report
− Process improvement analysis report
− Product need assessment
− Progress report
− Qualification test report
− Review minutes
− Service report
− Software unit test report
− User notification
− Validation report
− Verification report

Request

− Change request
− Customer satisfaction survey
− Request for proposal (RFP)
− Resource request
− Risk action request

Specification

− Contract
− Service level agreement (SLA)
− Software requirements specification
− System requirements specification
− Validation test specification
 
Цитата
Виктор Фигурнов пишет:
Цитата
убожетымой пишет:
Сегодня я была на одном собесе в компанию 1С, где меня загрузили вопросами по предметным областям (бухгалтерия, экономика и т.д.). Вопросы были из серии "На основании какого документа производится кладовщиком отгрузка продукции?" И подведением итога, что я вообще ничего не понимаю и не понятно, что я могла писать без этих сакральных знаний.
Я в документации не новичок: работала и в медицине, и в "нефти", и на предприятиях-производителях. Но никто не требовал от меня знание предметной области. Получается, чтобы писать про медицинское ПО я должна была 7 лет в Меде отучиться, чтобы писать "со знанием дела"? Иначе, "это простое описание кнопочек" (цитата чела из 1С)

А у Вас как с этим? Требуют знание предметной области? Или тех. писателю теперь надо в бухгалтерских законах разбираться, чтобы про проводки писать?
А как иначе? Без знания предметной области можно только про кнопки писать. О том, что видно на поверхности и понятно дилетанту. А получившуюся писанину потом специалист в предметной области должен внимательно прочесть и все ляпы выловить. Но это если важен качественный результат (у компании 1С именно такая ситуация), а не отписка для "галочки", что некий документ есть в наличии. Там, где нужна отписка, можно халтурить - писать не зная и не понимая предметной области, и лишь кое-как владея терминологией.
Но вопрос, по сути, в том, должен ли технический писатель знать предметную область уже на этапе собеседования? Или он, все-таки, должен изучать ее в процессе разработки документации?
Я считаю, что однозначно - в процессе разработки документации.
Допустим, я технический писатель, который ищет работу. За плечами опыт описания различных учетных систем. Но, вот, конкретно со складами дела не имела. Что ж теперь? Работодатель будет искать только технического писателя, который идеально знает складской учет?
Неразумно по нескольким причинам. Во-первых, в учете  любого предприятия есть свои нюансы (из опыта работы аналитиком), которые в любом случае надо изучать. Общие процессы учета как раз-таки изучаются довольно быстро, достаточно изучить нормативку. Во-вторых, технический писатель в таком случае должен быть переквалифицированным бизнес-аналитиком.
techwriter.ru.com
 
Виктор Фигурнов, на самом деле на собеседовании в Российской Федерации интересуются знанием РД 50-34.698-90 "Автоматизированные системы. Требования к содержанию документов".

И то этот документ носит рекомендательный характер, и на усмотрение Заказчика, который формирует требования к документации их прописывает явно в ТЗ на АС или компонент АС, сама документация может быть выполнена либо строго правил стандарта РД 50-34.698-90, либо с  допущениями. Эти допущения заключаются в возможности объединения в одну книгу некоторых самостоятельных документов - смотреть ГОСТ 34.201-89 "Виды, комплектность и обозначения документов при создании автоматизированных систем"... И список который я привёл ранее
Цитата
Орлов Андрей пишет:
Типы разрабатываемых документов

с переводом. (2 страницы)

PS: тоже из интернета
только позволяет закрыть пробел в знании английского языка  :)
 
Цитата
Андрей Орлов пишет:
Виктор Фигурнов , на самом деле на собеседовании в Российской Федерации интересуются знанием РД 50-34.698-90 "Автоматизированные системы. Требования к содержанию документов".
У меня и у моих знакомых про документ РД 50-34.698-90 никто ни разу не спрашивал. Документ крайне устарелый, ему уже 25 лет, да и в 1990 году он уже устарел. Например, если вы на собеседовании в фирме, занимающейся разработкой СУБД, расскажете о том, что там написано про документацию СУБД, о вас вряд ли сложится положительное впечатление.  :D
 
Цитата
techwriter пишет: Но вопрос, по сути, в том, должен ли технический писатель знать предметную область уже на этапе собеседования? Или он, все-таки, должен изучать ее в процессе разработки документации? Я считаю, что однозначно - в процессе разработки документации. Допустим, я технический писатель, который ищет работу. За плечами опыт описания различных учетных систем. Но, вот, конкретно со складами дела не имела. Что ж теперь? Работодатель будет искать только технического писателя, который идеально знает складской учет?
Специфика конкретной области может изучаться по ходу дела, но базовая подготовка должна быть. Если вы ничего не знаете о том, на основании каких документов производится отпуск товаров со склада, то основы учета вы в принципе не знаете, даже если имеете некий "опыт описания различных учетных систем". Учет это непростая область, и люди её по 5 лет в вузе изучают, а потом годы работают, и то бывает, что к ним приходят аудиторы и указывают многочисленные ошибки. А вы хотите за пару недель или месяцев освоить какую-то область учета так, чтобы правильно описывать учетные процессы и учить бухгалтеров и учетных работников тому, как им использовать программу для решения их задач. Извините, но это вряд ли получится.

Цитата
techwriter пишет: Работодатель будет искать только технического писателя, который идеально знает складской учет?
Это работодатель решит сам.

Цитата
techwriter пишет: Общие процессы учета как раз-таки изучаются довольно быстро, достаточно изучить нормативку.
Крайне сомнительно. Учет нельзя быстро изучить, прочитав нормативку, юристом нельзя быстро стать, прочитав законы, и т.д. Не знаю ни одного исключения.

Цитата
techwriter пишет: Общие процессы учета как раз-таки изучаются довольно быстро, достаточно изучить нормативку. Во-вторых, технический писатель в таком случае должен быть переквалифицированным бизнес-аналитиком.
Бизнес-аналитик изучает бизнес-ситуацию, чтобы определить проблемы и возможности бизнеса, и на основе их анализа предложить решения, позволяющие организации достичь своих целей. Технический писатель ничем подобным не занимается.
 
Цитата
Виктор Фигурнов пишет:
Специфика конкретной области может изучаться по ходу дела, но базовая подготовка должна быть. Если вы ничего не знаете о том, на основании каких документов производится отпуск товаров со склада, то основы учета вы в принципе не знаете, даже если имеете некий "опыт описания различных учетных систем". Учет это непростая область, и люди её по 5 лет в вузе изучают, а потом годы работают, и то бывает, что к ним приходят аудиторы и указывают многочисленные ошибки. А вы хотите за пару недель или месяцев освоить какую-то область учета так, чтобы правильно описывать учетные процессы и учить бухгалтеров и учетных работников тому, как им использовать программу для решения их задач. Извините, но это вряд ли получится.
Виктор, процессы УЖЕ должны быть описаны в фирме бизнес-аналитиками в аналитической документации. ТЗ как раз-таки не должно быть в виде: "разработать такую-то форму, которая должная содержать такие-то элементы". В функции технического писателя описание бизнес-процесса вообще не входит. В его функции входит описание действий пользователя в системе для достижения той или иной цели. В сложном документообороте один документ может вообще участвовать в нескольких схемах документооборота и при этом иметь разное поведение в зависимости от действий, которые необходимо с ним выполнить. Все схемы, опять же, должны быть описаны бизнес-аналитиком. Техническому писателю достаточно при налаженном процессе бизнес-анализа и документирования процессов ознакомиться с нормативкой и документацией по процессам. Если вам на собеседовании внезапно сказали, что технический писатель - это и жнец, и жрец, и на бубе игрец, то от такого работодателя надо бежать, роняя тапки, т.к. процессы разработки там на уровне примитива.
techwriter.ru.com
 
Цитата
Виктор Фигурнов пишет:
Крайне сомнительно. Учет нельзя быстро изучить, прочитав нормативку, юристом нельзя быстро стать, прочитав законы, и т.д. Не знаю ни одного исключения.
А вы и не юрист, понимаете? Ваша задача заключается не в том, что объяснить юристы все "буквы закона". Ваша задача - описать, как в автоматизированной системе выполнить нужное ему действие. Или вы считаете, что если бухгалтер печатает журнал проводок, то он не знает, что такое проводка и ему необходимо рассказывать, что это такое?
techwriter.ru.com
 
Цитата
Виктор Фигурнов пишет:
Бизнес-аналитик изучает бизнес-ситуацию, чтобы определить проблемы и возможности бизнеса,
Бизнес-аналитик этим вообще не занимается. Этим занимается специальный эксперт, который пишет бизнес-план. Бизнес-аналитик изучает потребности пользователя.
techwriter.ru.com
 
Цитата
Виктор Фигурнов пишет:
Цитата
Андрей Орлов пишет:
Виктор Фигурнов , на самом деле на собеседовании в Российской Федерации интересуются знанием РД 50-34.698-90 "Автоматизированные системы. Требования к содержанию документов".
У меня и у моих знакомых про документ РД 50-34.698-90 никто ни разу не спрашивал. Документ крайне устарелый, ему уже 25 лет, да и в 1990 году он уже устарел. Например, если вы на собеседовании в фирме, занимающейся разработкой СУБД, расскажете о том, что там написано про документацию СУБД, о вас вряд ли сложится положительное впечатление.
Если заказчики  - это НИИ, министерства и ведомства, то считайте и читайте так: "фирма получает госзаказы, которые гарантирует её стабильность, фирма штат которой 200 человек минимум, и для этих заказчиков следование букве РД 50-34.698-90 обязательно"   :o
 
Цитата
techwriter пишет:
Цитата
Виктор Фигурнов пишет:
Бизнес-аналитик изучает бизнес-ситуацию, чтобы определить проблемы и возможности бизнеса,
Бизнес-аналитик этим вообще не занимается. Этим занимается специальный эксперт, который пишет бизнес-план. Бизнес-аналитик изучает потребности пользователя.
Вы ошибаетесь.

http://en.wikipedia.org/wiki/Business_analyst
http://ru.wikipedia.org/wiki/Бизнес-аналитик
 
Цитата
Виктор Фигурнов пишет:
Цитата
techwriter пишет:
Цитата
Виктор Фигурнов пишет:
Бизнес-аналитик изучает бизнес-ситуацию, чтобы определить проблемы и возможности бизнеса,
Бизнес-аналитик этим вообще не занимается. Этим занимается специальный эксперт, который пишет бизнес-план. Бизнес-аналитик изучает потребности пользователя.
Вы ошибаетесь.

http://en.wikipedia.org/wiki/Business_analyst
http://ru.wikipedia.org/wiki/Бизнес-аналитик
Господа  :)  .... из вас каждый по своему прав, только следует уточнить: бизнес-аналитик в какой области / сфере деятельности, например существует
1) бизнес-аналитик на бирже, который изучает бизнес-ситуацию на основе экономических показателей  и графиков движения курсов с помощью специальных инструментов отличных от CASE-средств и строит прогнозы / модели развития экономики / курсов валют.
2) бизнес-аналитик в ИТ-сфере, который изучает бизнес-ситуацию или её фрагмент с помощью CASE-средств и строит / описывает механизмы и модели для формализации задач программной разработки.

Как-то так.
 
Цитата
techwriter пишет: Ваша задача - описать, как в автоматизированной системе выполнить нужное ему действие. Или вы считаете, что если бухгалтер печатает журнал проводок, то он не знает, что такое проводка и ему необходимо рассказывать, что это такое?
В пользовательской документации по 1С:Бухгалтерии версий 4, 5 и 6, которую я в 1993-95 гг. писал для 1С, определение проводки было. И определения других базовых понятий тоже. Но тогда было другое время, и бухгалтерией очень часто занимались непрофессионалы. Сейчас я не уверен, что поступил бы так же.

Проблема в том, что вы должны не только рассказать, как выполнять действие, но и что это за действие. Часто также надо указать, когда и почему оно выполняется. Иногда также необходимо указать, в соответствии с какими  требованиями оно должно выполняться, какие имеются типичные ошибки при его выполнении, и т.д. Иногда надо объяснить, почему выбран именно такой способ выполнения этого действия, а не иной... В терминологии DITA - нужно описывать не только task, но до нее изложить concept, а после нее дать reference. Не зная предметной области автоматизированной системы, задач и потребностей её пользователей, вы сможете сделать документацию на уровне примитивного описания кнопок, не более. И если предметная область хоть сколько-либо сложная, то получившуюся писанину придется показывать специалисту, чтобы он нашел и вычистил все ляпы.
 
Вообще, правилами хорошего тона допустимо вводить и разрабатывать раздел "Термины и определения" или раздел "Список сокращений" в руководстве пользователя, если такие разделы вносят ясность и однозначность в понимание пользователем принципов работы с программным продуктом.
 
Цитата
Виктор Фигурнов пишет:
Цитата
techwriter пишет: Ваша задача - описать, как в автоматизированной системе выполнить нужное ему действие. Или вы считаете, что если бухгалтер печатает журнал проводок, то он не знает, что такое проводка и ему необходимо рассказывать, что это такое?
В пользовательской документации по 1С:Бухгалтерии версий 4, 5 и 6, которую я в 1993-95 гг. писал для 1С, определение проводки было. И определения других базовых понятий тоже. Но тогда было другое время, и бухгалтерией очень часто занимались непрофессионалы. Сейчас я не уверен, что поступил бы так же.

Проблема в том, что вы должны не только рассказать, как выполнять действие, но и что это за действие. Часто также надо указать, когда и почему оно выполняется. Иногда также необходимо указать, в соответствии с какими требованиями оно должно выполняться, какие имеются типичные ошибки при его выполнении, и т.д. Иногда надо объяснить, почему выбран именно такой способ выполнения этого действия, а не иной... В терминологии DITA - нужно описывать не только task, но до нее изложить concept, а после нее дать reference. Не зная предметной области автоматизированной системы, задач и потребностей её пользователей, вы сможете сделать документацию на уровне примитивного описания кнопок, не более. И если предметная область хоть сколько-либо сложная, то получившуюся писанину придется показывать специалисту, чтобы он нашел и вычистил все ляпы.
Надо знать не предметную область как таковую, а автоматизируемый процесс, который, как правило, покрывает только часть предметной области. Если у вас автоматизируется бухгалтерский учет коммерческой организации, это не значит, что вам нужно знать бухгалтерский учет бюджетной организации. При этом вы знаете, что такое хозоперации, проводки, дебет, кредит, т.е. общие понятия. Но если вы пойдете устраиваться в контору, которая автоматизирует бухгалтерский учет бюджетного учреждения, неужели вы долго будете изучать автоматизируемый процесс?
Понятие проводки имеет смысл описывать только в том случае, если у вас целевая аудитория - специалисты, которые занимаются разработкой ПО в вашей системе и которые действительно впервые видят проводку. Но ситуация странная, если у кандидатов при приеме на работу требуют отличного знания предметной области.
Писать бухгалтеру, что такое проводка, бессмысленно (я бы даже сказала, неуважительно). Он не будет это читать и будет пропускать ваш раздел с терминами и определениями. А если ваши термины и определения по предметной области и системе собраны в одну кучу, то возникнет ситуация, когда бухгалтер его просто пропустит, увидев, например, первое слово "амортизация".
techwriter.ru.com
Страницы: 1 2 След.
Читают тему