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

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1 2 След.
Ответить
RSS
Обратное проектирование
 
Добрый день!
У компании есть готовый работающий проект. Необходимо по коду программы (Java) выполнить описание программы. За основу будет взят ГОСТ 19.402-78. Вопрос заключается в следующем: с какой стороны подойти к этому исходному коду, учитывая, что опыта программирования на Java нет? Т.е. параллельно нужно будет изучать Java  и основы ООП. Исходный код содержит множество модулей, как понять с какого начать описание?
 
Добрый день!
Если честно, задача странная. Ею должен заниматься специалист, который знает Java либо хотя бы имеет о ней представление.
Но если она так поставлена, то надо сначала изучить основы ООП и Java, затем проконсультироваться с разработчиками (им виднее, что они там накодили) и потом уже приступать.
techwriter.ru.com
 
Да. Задача уже поставлена. Получается, что консультироваться с разработчиками придется постоянно. Модулей куча! Сейчас параллельно в работе три процесса: изучение основ ООП, Java и исходников. И беспокоит то, сколько разработчик будет отвечать на вопросы? Ведь чем глубже погружаешься в задачу, тем больше вопросов возникает. Возможно некоторые вопросы неоднократно.
 
Цитата
TatLeo пишет:
Да. Задача уже поставлена. Получается, что консультироваться с разработчиками придется постоянно. Модулей куча! Сейчас параллельно в работе три процесса: изучение основ ООП, Java и исходников. И беспокоит то, сколько разработчик будет отвечать на вопросы? Ведь чем глубже погружаешься в задачу, тем больше вопросов возникает. Возможно некоторые вопросы неоднократно.
Если в проекте есть менеджер, то до него имеет смысл  довести, что для решения задачи требуется постоянная консультация разработчиков. Это поможет избежать затягивание предоставления ответов.
techwriter.ru.com
 
Ответы не затягиваются, с этим все в порядке. Беспокоюсь, что рано или поздно может наступить предел( И скажут, что задачу нужно было выполнить вчера
 
Цитата
TatLeo пишет:
Ответы не затягиваются, с этим все в порядке. Беспокоюсь, что рано или поздно может наступить предел( И скажут, что задачу нужно было выполнить вчера
ну это уже как вы спланируете и утвердите сроки с менеджером проекта. Сначала планируем, потом пишем.
 
Точно нужно настолько детальное описание программы, что необходимо погружаться в код на Java?

Разделы документа по ГОСТу:
  • общие сведения;
  • функциональное назначение;
  • описание логической структуры;
  • используемые технические средства;
  • вызов и загрузка;
  • входные данные;
  • выходные данные.
Знание кода может потребоваться в одном пункте из 7 - "Описание логической структуры". А может и не потребоваться. Бывает достаточно написать, что программа состоит из таких-то модулей, каждый из которых отвечает за такую-то функциональность. Добавить схему взаимодействия этих модулей. Об этом должен иметь представление менеджер проекта или системный архитектор. И это можно рассказать, не зная языка, на котором эти модули реализованы.
 
Цитата
techwriter пишет:
Если честно, задача странная. Ею должен заниматься специалист, который знает Java либо хотя бы имеет о ней представление.
:)   А техпис чем тогда должен заниматься? Техпис должен разбираться и описывать.
Из букв составлять слова, если знает алфавит?

Цитата
TatLeo пишет:
Вопрос заключается в следующем: с какой стороны подойти к этому исходному коду, учитывая, что опыта программирования на Java нет? Т.е. параллельно нужно будет изучать Javaи основы ООП.
Параллельно изучать Java и ООП можно (для себя), но не нужно для выполнения задачи.

Цитата
TatLeo пишет:
Исходный код содержит множество модулей, как понять с какого начать описание?
Да с того, какой больше нравится или спросить у разработчиков какой самый сложный и важный и с него начать. Описывать сначала сложные лучше, пользуясь скидкой на незнание основ Java, остальные модули потом проще будет описывать.
 
Цитата
ADVANCED пишет:

А техпис чем тогда должен заниматься? Техпис должен разбираться и описывать.
Из букв составлять слова, если знает алфавит?
Технический писатель не специалист?
Разбираться в чём? В коде, написанном кем-то?
Чтобы в нём разобраться, требуется много трудозатрат с учётом того, что технический писатель его ни разу в данном случае в глаза не видел. Поэтому с менеджерской точки зрения задача поставлена убого, без вникания в риски, к которым это приведёт. Написать абы чё может каждый. Написать хорошую подробную документацию - только тот, кто детально разбирается в предмете того, что описывает.
Если технический писатель не знает даже основ ООП, то что он выдаст на выходе?
Изменено: techwriter - 27.01.2015 10:01:39
techwriter.ru.com
 
Спасибо за обсуждение! Начала с того, что строю диаграмму классов, далее диаграмму последовательностей. Во многом "для себя", чтобы понять как устроена система. Далее приступлю к созданию документа по ГОСТу.
Оказалось интересно, надеюсь справлюсь.
Изменено: TatLeo - 28.01.2015 11:56:43
 
С менеджерской точки зрения задача поставлено нормально. Если у менеджера нет свободного программиста для описания, он ставит задачу техническому писателю, если техпис не способен, то менеджер будет описывать сам. Так работает большинство компаний и ничего криминального тут нет.

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

Цитата
techwriter пишет:
Если технический писатель не знает даже основ ООП, то что он выдаст на выходе?
У него появляется стимул начать разбираться. Самая большая проблема - "НАЧАТЬ", а далее человек втягивается, ему становится интересно и разбирается понемногу. Если не интересно, то профессия не его.

Техническому писателю приходится разбираться в архитектуре, в коде, в алгоритмах, в концепциях того или иного продукта. Такова работа. Поверь, далее это пригодится.

Автор темы уже заинтересован и вопрос был "с чего начать".


Цитата
TatLeo пишет:
Начала с того, что строю диаграмму классов, далее диаграмму последовательностей. Во многом "для себя", чтобы понять как устроена система.
Правильно

Цитата
TatLeo пишет:
Далее приступлю к созданию документа по ГОСТу.
Далее описать назначение всех модулей, алгоритмы их работы и форматы взаимодействия между ними (следуя все той же диаграмме). При этом в первую очередь критически важные модули, без которых ничего не будет работать (ядро, модули обработки данных), а во вторую дополнительные (типа уведомлений, экспорта/импорта, архивации и аудита)

По ГОСТ потом можно начинать оформлять.
 
Спасибо за советы! Тема не закрывается, т.к. далее будет еще много вопросов. Так можно?
 
Цитата
TatLeo пишет:
Спасибо за советы! Тема не закрывается, т.к. далее будет еще много вопросов. Так можно?
Можно, но хотелось бы посмотреть как вы закроете тему ))
 
Цитата
ADVANCED пишет:
Можно, но хотелось бы посмотреть как вы закроете тему ))
Возможно неправильно выразилась) Не так часто на форумах общаюсь
 
Цитата
ADVANCED пишет:
У него появляется стимул начать разбираться. Самая большая проблема - "НАЧАТЬ", а далее человек втягивается, ему становится интересно и разбирается понемногу. Если не интересно, то профессия не его.

Техническому писателю приходится разбираться в архитектуре, в коде, в алгоритмах, в концепциях того или иного продукта. Такова работа. Поверь, далее это пригодится.

Автор темы уже заинтересован и вопрос был "с чего начать".
Угу. Ты мне так рассказываешь, как будто я документации для программистов не писала... Поэтому на "поверь" могу ответить своё "поверь", что на выходе качественного документа не выйдет, если технический писатель не в теме. Вряд ли он сможет на начальном этапе даже грамотно вопросы программисту задать. Поэтому обучаться программированию надо было в свободное время на тренингах до получения подобных задач. Моё мнение - сначала надо дорасти до определённого уровня, а потом уже браться за подобные задачи.
Если документация не имеет практического применения, то можно, конечно, писать как хочешь и что хочешь. Но абсолютно уверена, что бест практис для программистов может написать только гуру-программист.
techwriter.ru.com
 
В условии задачи не сказано, что документ пишется для программистов.
 
Цитата
techwriter пишет:
Поэтому обучаться программированию надо было в свободное время на тренингах до получения подобных задач. Моё мнение - сначала надо дорасти до определённого уровня, а потом уже браться за подобные задачи.
Если документация не имеет практического применения, то можно, конечно, писать как хочешь и что хочешь. Но абсолютно уверена, что бест практис для программистов может написать только гуру-программист.
Именно поэтому нет "бэст практис" и возникает нужда их написать тем, кто не занят задачами по спасению планеты  :)  Гуру-программист не будет писать это.

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

В данном случае есть цель описать сущности, классы и архитектуру ПО. Для изучения инструментов, цель разбивается на подцели: что такое сущности, классы, объекты, методы, функции, вызовы, как они зависят друг от друга и влияют, изучается терминология Java в этом контексте и так далее. В идеале установить среду в которой разрабатывалось ПО (netbeans, eclipse и пр), взять исходники программы, найти зависимости, описать справочники, переменные, описать вызовы с примером кода вызова методов, процедур и пр. Собрать все это дело и описать по шагам этапы сборки, логирования, параметров для последующей инсталляции и так. далее.

Просто взять и выучить все сразу не получится. Сама же говоришь, что нельзя знать какие вопросы задавать программистам и аналогично не будешь знать что изучать.
 
Цитата
ADVANCED пишет:
Изучать языки программирования в теории только для того, чтобы в будущем писать какую-то документацию -тупиковый путь. Должна быть цель.
Зачем в теории? Изучай на практике.
techwriter.ru.com
 
:evil:  писал писал и ошибка сохранения...
 
Цитата
ADVANCED пишет:
Для изучения инструментов, цель разбивается на подцели: что такое сущности, классы, объекты, методы, функции, вызовы, как они зависят друг от друга и влияют, изучается терминология Java в этом контексте и так далее. В идеале установить среду в которой разрабатывалось ПО (netbeans, eclipse и пр), взять исходники программы, найти зависимости, описать справочники, переменные, описать вызовы с примером кода вызова методов, процедур и пр. Собрать все это дело и описать по шагам этапы сборки, логирования, параметров для последующей инсталляции и так. далее.
Спасибо за полезную информацию! Учту
 
Цитата
ADVANCED пишет:
Для изучения инструментов, цель разбивается на подцели: что такое сущности, классы, объекты, методы, функции, вызовы, как они зависят друг от друга и влияют, изучается терминология Java в этом контексте и так далее.
В процессе. Постоянно обращаюсь к соответствующей литературе.
 
Цитата
ADVANCED пишет:
В идеале установить среду в которой разрабатывалось ПО (netbeans, eclipse и пр), взять исходники программы, найти зависимости
Сделано.
Изменено: TatLeo - 30.01.2015 14:39:44
 
Цитата
ADVANCED пишет:
описать справочники, переменные, описать вызовы с примером кода вызова методов, процедур и пр. Собрать все это дело и описать по шагам этапы сборки, логирования, параметров для последующей инсталляции и так. далее.
Можно подробнее? Или, если есть шаблоны какие то, стандарты или ГОСТы, можно их посмотреть?
 
Цитата
TatLeo пишет:
Цитата
ADVANCED пишет:
Для изучения инструментов, цель разбивается на подцели: что такое сущности, классы, объекты, методы, функции, вызовы, как они зависят друг от друга и влияют, изучается терминология Java в этом контексте и так далее.
В процессе. Постоянно обращаюсь к соответствующей литературе.



Ну и всякие описалова типа http://www.helloworld.ru/texts/comp/lang/java/java/07.htm + соседние страницы
 
Цитата
TatLeo пишет:

Можно подробнее? Или, если есть шаблоны какие то, стандарты или ГОСТы, можно их посмотреть?
Не было возможности сохранить, описывал во внутренней Вики для java-разработчиков. Стандартов никаких нет. Это просто перечисление всех сущностей, которые используются в вашем ПО и правил их использования. Бывают соглашения на разработку сущностей, которые формализованы между разработчиками, типа в одном стиле, чтобы было удобно читать код друг друга
Страницы: 1 2 След.
Ответить
Читают тему
Форма ответов
 
Текст сообщения*
Загрузить файл или картинкуПеретащить с помощью Drag'n'drop
Перетащите файлы
Ничего не найдено
Загрузить файлы
Отправить Отменить