Далее, идет процесс создания программы - это разработка или физическая реализация проекта

Я правильно понимаю?

ГОСТ Р ИСО/МЭК 12207-2010 Информационная технология (ИТ). Системная и программная инженерия. Процессы жизненного цикла программных средств

Все сложнее на пару порядков, но хотя бы порядок стадий правильный =)

Например – есть отдельный Проект на ПО, он идет после ТЗ.

А проект можно рассматривать как синоним продукта? В определённом контексте, конечно

То есть проект на ПО  - это продукт, результат процесса проектирования (условно создания продукта). Правильно?

все что угодно можно расценивать, как продукт, если вы Sale manager

😆

проект не является синонимом слова продукт, но может являться продуктом (например у проектной организации)

Спасибо большое за ответа!!! Буду разбираться!!!

Добрый вечер! Я пока не технический писатель, но присматриваюсь к профессии, потому что моя компания хочет нанять первого писателя. Вот пытаюсь понять, вдруг это могу быть я.

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

И уже на этом пункте у меня непонимание, либо гуглю не то и не так. Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.

То есть, зачем апи описывается красиво для внешнего пользователя и зачем там техпис, понятно. Сваггер малость уродлив, надо больше вводных и т.п.

Но какова роль техписа в описании апи для внутреннего использования? Или может, инструменты другие надо брать, чтобы дополнить описание в сваггере чем-то? Но чем и зачем?Мне raml понравился, но насколько он используется внутри и чем выгоднее сваггера?

Чувствую, что в корне не понимаю чего-то про внутреннюю документацию апи. Помогите разобраться, пожалуйста, ткните, что посмотреть. Курс Тома Джонсона помогает разобраться в апи, но там больше про внешнюю документацию, как понимаю. Что же с внутренней?

описывается подробно и понятно обычно OpenAPI. тексты внутреннего пользования обычно до ума не доводят по принципу экономии усилий (по тому же принципу и внеш. документацию не всегда успевают). но новым сотрудникам или тем, кому нужен кусок чужого проекта, проще, когда этот проект документирован нормально.

я сейчас не только про описания API.

казалось бы, для своих можно без стиля и прочих церемоний, но я заметила, что необходимость «церемониться» (и образ беспомощно застывшего читателя) меня очень дисциплинирует. а когда пишу для себя и «таких, как я» (очень умных людей, понимающих с лету, шутка), то уже через несколько недель не понимаю некоторые детали написанного мной же.

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

Работал в многотысячной компании. Там был большой портал документации по проектам компании, по модулям, многое было описано. Но также очень много статей на этом портале состояли из многообещающей аббревиатуры "TBD" (To Be Done). Причем зачастую эти статьи были созданы единожды с этой аббревиатурой и более не менялись в течение лет, история ревизий не даст соврать)

Поверьте, там не просто «засунул»)) там описал правильно https://swagger.io/specification/
Иначе никакой «автогенерации»

Очень много copy paste и для разработчика это не профильное занятие.
Но обычно делают и сами на малых проектах.

Но вот читать что тех райтер нужен для внутренней документации в маленькой компании это что-то интересное)
Документацию пишет каждый от себя. И никто лучше самого тим лида, разработчик, пиема или результаты теста самого человека не опишут. А что при этом делал бы тех райтер. Ходил за каждым и записывал как секретарь спросив что записать?)

Раз не сделано, значит приоритет низкий.

TBD - вроде to be decided/determined. Больше в ТЗ (и да, проекты, бывает, реализуются, когда в ТЗ сплошные TBD...)

У меня созрело еще одно уточнение, в какой компании продуманная даже (🥲) внутренняя документация: над _одним_ проектом работает несколько сотен людей. Возможно, у вас так и было. Привожу этот доп. пример, чтобы было отличие от многотысячных компаний с мелкими проектами, по 10-100 человек, которые по внутренним процессам - как отдельные компании, им не нужно работать _вместе_.

Могу предположить, что разработчики хотят перестать писать комменты к своему же коду, из которых впоследствии и автогенерируется дока. Сталкивалась с таким сама, и наблюдала со стороны - коллега ушла в новую контору и занималась именно этим

Добрый вечер! Я пока не технический писатель, но присматриваюсь к профессии, потому что моя компания хочет нанять первого писателя. Вот пытаюсь понять, вдруг это могу быть я.

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

И уже на этом пункте у меня непонимание, либо гуглю не то и не так. Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.

То есть, зачем апи описывается красиво для внешнего пользователя и зачем там техпис, понятно. Сваггер малость уродлив, надо больше вводных и т.п.

Но какова роль техписа в описании апи для внутреннего использования? Или может, инструменты другие надо брать, чтобы дополнить описание в сваггере чем-то? Но чем и зачем?Мне raml понравился, но насколько он используется внутри и чем выгоднее сваггера?

Чувствую, что в корне не понимаю чего-то про внутреннюю документацию апи. Помогите разобраться, пожалуйста, ткните, что посмотреть. Курс Тома Джонсона помогает разобраться в апи, но там больше про внешнюю документацию, как понимаю. Что же с внутренней?

За инструменты не скажу. Описание api нужно для управления контрактами обмена/данными. В компании, на уровень абстракции выше кода. Особенно если у вас микросервисы. Системы начнут расти как грибы, и если не будет документации, черт ногу сломит что происходит. И начнутся дубли, гонка данных. Потому что таска в джире будет делаться из знания одного разработчика, а не картины api и данных для бизнеса.

Для нашей компании была задача найти инструментарий  для описания REST API  Рассматривали варианты из популярных языков описания: Open API, Blueprint и RAML. В результате выбрали стандарт Open API по следующим причинам: стандарт имеет большое сообщество и много информации с описанием, основан на yaml формате файлов, которые очень удобно переиспользовать, большое количество инструментов для работы.
В качестве платформы для визуализации описаний из yaml выбрали ReDoc (https://redocly.github.io/redoc/). Возможно вкусовщина, но  Swagger не так красиво отрисовывает. Однако у ReDoc в текущей версии есть недостаток, он не умеет отображать по умолчанию xml представление запросов и ответов, хотя через костыль (example) все работает.
Если не хватает знаний формата Open API, то очень сильно помогает конструктор описаний Stoplight studio, в котором есть визуальная среда и откуда потом можно брать готовый yaml файл (https://stoplight.io/studio/)