М
Для размещения и сборки из разных схем yaml развернули Gitlab, а для написания используем Visual Studio Code.
Size: a a a
2021 January 20
NV
Михаил
Для размещения и сборки из разных схем yaml развернули Gitlab, а для написания используем Visual Studio Code.
Красавчики, всё хорошо делаете )
NV
Добрый вечер! Я пока не технический писатель, но присматриваюсь к профессии, потому что моя компания хочет нанять первого писателя. Вот пытаюсь понять, вдруг это могу быть я.
Компания молодая, большинство процессов создается с нуля. Ответ на вопрос, зачем техпис: чтобы разработчики занимались разработкой. Писать надо внутреннюю документацию апи, думают вот сваггером пользоваться.
И уже на этом пункте у меня непонимание, либо гуглю не то и не так. Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
То есть, зачем апи описывается красиво для внешнего пользователя и зачем там техпис, понятно. Сваггер малость уродлив, надо больше вводных и т.п.
Но какова роль техписа в описании апи для внутреннего использования? Или может, инструменты другие надо брать, чтобы дополнить описание в сваггере чем-то? Но чем и зачем?Мне raml понравился, но насколько он используется внутри и чем выгоднее сваггера?
Чувствую, что в корне не понимаю чего-то про внутреннюю документацию апи. Помогите разобраться, пожалуйста, ткните, что посмотреть. Курс Тома Джонсона помогает разобраться в апи, но там больше про внешнюю документацию, как понимаю. Что же с внутренней?
Компания молодая, большинство процессов создается с нуля. Ответ на вопрос, зачем техпис: чтобы разработчики занимались разработкой. Писать надо внутреннюю документацию апи, думают вот сваггером пользоваться.
И уже на этом пункте у меня непонимание, либо гуглю не то и не так. Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
То есть, зачем апи описывается красиво для внешнего пользователя и зачем там техпис, понятно. Сваггер малость уродлив, надо больше вводных и т.п.
Но какова роль техписа в описании апи для внутреннего использования? Или может, инструменты другие надо брать, чтобы дополнить описание в сваггере чем-то? Но чем и зачем?Мне raml понравился, но насколько он используется внутри и чем выгоднее сваггера?
Чувствую, что в корне не понимаю чего-то про внутреннюю документацию апи. Помогите разобраться, пожалуйста, ткните, что посмотреть. Курс Тома Джонсона помогает разобраться в апи, но там больше про внешнюю документацию, как понимаю. Что же с внутренней?
Думаю, что работа над документацией API — это очень хорошее начало карьеры техписателя.
> Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
Во-первых, из сигнатуры метода не всё можно вытащить. Параметры — да, их смысл — нет. Писатель может добавить понятные описания эндпойнта, параметров или структуры данных запроса, всего того же самого для ответа, пред- и постусловий вызова. Ещё очень помогают хорошие примеры.
Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
> Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
Во-первых, из сигнатуры метода не всё можно вытащить. Параметры — да, их смысл — нет. Писатель может добавить понятные описания эндпойнта, параметров или структуры данных запроса, всего того же самого для ответа, пред- и постусловий вызова. Ещё очень помогают хорошие примеры.
Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
L
Думаю, что работа над документацией API — это очень хорошее начало карьеры техписателя.
> Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
Во-первых, из сигнатуры метода не всё можно вытащить. Параметры — да, их смысл — нет. Писатель может добавить понятные описания эндпойнта, параметров или структуры данных запроса, всего того же самого для ответа, пред- и постусловий вызова. Ещё очень помогают хорошие примеры.
Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
> Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
Во-первых, из сигнатуры метода не всё можно вытащить. Параметры — да, их смысл — нет. Писатель может добавить понятные описания эндпойнта, параметров или структуры данных запроса, всего того же самого для ответа, пред- и постусловий вызова. Ещё очень помогают хорошие примеры.
Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
Согласна со всем выше и добавлю ещё пять копеек: можно выяснить и описать ограничения и дефолтные значения полей, в общей части можно описать авторизацию, throttling и подобные ему особенности нагрузки, коды ошибок, какие-то sla, рассказать о сценариях использования
L
Добрый вечер! Я пока не технический писатель, но присматриваюсь к профессии, потому что моя компания хочет нанять первого писателя. Вот пытаюсь понять, вдруг это могу быть я.
Компания молодая, большинство процессов создается с нуля. Ответ на вопрос, зачем техпис: чтобы разработчики занимались разработкой. Писать надо внутреннюю документацию апи, думают вот сваггером пользоваться.
И уже на этом пункте у меня непонимание, либо гуглю не то и не так. Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
То есть, зачем апи описывается красиво для внешнего пользователя и зачем там техпис, понятно. Сваггер малость уродлив, надо больше вводных и т.п.
Но какова роль техписа в описании апи для внутреннего использования? Или может, инструменты другие надо брать, чтобы дополнить описание в сваггере чем-то? Но чем и зачем?Мне raml понравился, но насколько он используется внутри и чем выгоднее сваггера?
Чувствую, что в корне не понимаю чего-то про внутреннюю документацию апи. Помогите разобраться, пожалуйста, ткните, что посмотреть. Курс Тома Джонсона помогает разобраться в апи, но там больше про внешнюю документацию, как понимаю. Что же с внутренней?
Компания молодая, большинство процессов создается с нуля. Ответ на вопрос, зачем техпис: чтобы разработчики занимались разработкой. Писать надо внутреннюю документацию апи, думают вот сваггером пользоваться.
И уже на этом пункте у меня непонимание, либо гуглю не то и не так. Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
То есть, зачем апи описывается красиво для внешнего пользователя и зачем там техпис, понятно. Сваггер малость уродлив, надо больше вводных и т.п.
Но какова роль техписа в описании апи для внутреннего использования? Или может, инструменты другие надо брать, чтобы дополнить описание в сваггере чем-то? Но чем и зачем?Мне raml понравился, но насколько он используется внутри и чем выгоднее сваггера?
Чувствую, что в корне не понимаю чего-то про внутреннюю документацию апи. Помогите разобраться, пожалуйста, ткните, что посмотреть. Курс Тома Джонсона помогает разобраться в апи, но там больше про внешнюю документацию, как понимаю. Что же с внутренней?
Эх, чутка бы попозже этот вопрос) написал на праздниках статью как раз по теме, скоро должна выйти на хабре)
L
Правда ответ там про то, что задача техписа наладить процесс, а саму доку все равно делать разрабам.
L
Могу предположить, что разработчики хотят перестать писать комменты к своему же коду, из которых впоследствии и автогенерируется дока. Сталкивалась с таким сама, и наблюдала со стороны - коллега ушла в новую контору и занималась именно этим
Перестать писать комменты к коду это сильно) в моем случае ключевым оказалось как раз таки донести мысль, что это необходимо и всем от этого будет проще и лучше
A
Большое спасибо за отклик всем! Пойду погружаться в тему и инструменты дальше. И очень жду статью на хабре)
L
Думаю, на следующей неделе точно будет, скину сюда обязательно!
Там будет немного рассуждений как раз о роли техписа в процессе, а потом подробнее про swagger-php и немного про кастомизацию swagger-ui, надеюсь будет полезно)
Там будет немного рассуждений как раз о роли техписа в процессе, а потом подробнее про swagger-php и немного про кастомизацию swagger-ui, надеюсь будет полезно)
СФ
Думаю, что работа над документацией API — это очень хорошее начало карьеры техписателя.
> Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
Во-первых, из сигнатуры метода не всё можно вытащить. Параметры — да, их смысл — нет. Писатель может добавить понятные описания эндпойнта, параметров или структуры данных запроса, всего того же самого для ответа, пред- и постусловий вызова. Ещё очень помогают хорошие примеры.
Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
> Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
Во-первых, из сигнатуры метода не всё можно вытащить. Параметры — да, их смысл — нет. Писатель может добавить понятные описания эндпойнта, параметров или структуры данных запроса, всего того же самого для ответа, пред- и постусловий вызова. Ещё очень помогают хорошие примеры.
Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
> Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
Я тоже с ходу про это вспомнил, но в изначальном вопросе речь шла о внутренней, а не о внешней документации.
В нашей практике тьюториалы на API, адресованные «внутрь» никому особо не нужны ( = их ценность не так велика, и ее сложно подсветить/продать бизнесу)
Я тоже с ходу про это вспомнил, но в изначальном вопросе речь шла о внутренней, а не о внешней документации.
В нашей практике тьюториалы на API, адресованные «внутрь» никому особо не нужны ( = их ценность не так велика, и ее сложно подсветить/продать бизнесу)
KG
Именно это мне на днях втолковывали коллеги-программисты на кофепоинте, мол, идеальный код в комментариях не нуждается
KG
Переслано от Lejbron
Перестать писать комменты к коду это сильно) в моем случае ключевым оказалось как раз таки донести мысль, что это необходимо и всем от этого будет проще и лучше
NV
Именно это мне на днях втолковывали коллеги-программисты на кофепоинте, мол, идеальный код в комментариях не нуждается
Наивные )
AY
Именно это мне на днях втолковывали коллеги-программисты на кофепоинте, мол, идеальный код в комментариях не нуждается
а как новенькие будут учиться?
KG
Страданием))))
AY
> Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
Я тоже с ходу про это вспомнил, но в изначальном вопросе речь шла о внутренней, а не о внешней документации.
В нашей практике тьюториалы на API, адресованные «внутрь» никому особо не нужны ( = их ценность не так велика, и ее сложно подсветить/продать бизнесу)
Я тоже с ходу про это вспомнил, но в изначальном вопросе речь шла о внутренней, а не о внешней документации.
В нашей практике тьюториалы на API, адресованные «внутрь» никому особо не нужны ( = их ценность не так велика, и ее сложно подсветить/продать бизнесу)
то же самое - а как будут учиться новые люди?
KG
Ну или освоят навык телепатии)))
ET
Думаю, что работа над документацией API — это очень хорошее начало карьеры техписателя.
> Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
Во-первых, из сигнатуры метода не всё можно вытащить. Параметры — да, их смысл — нет. Писатель может добавить понятные описания эндпойнта, параметров или структуры данных запроса, всего того же самого для ответа, пред- и постусловий вызова. Ещё очень помогают хорошие примеры.
Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
> Что в сваггере делать техпису? Это же автогенерация, разработчик засунул метод туда новый и все.
Во-первых, из сигнатуры метода не всё можно вытащить. Параметры — да, их смысл — нет. Писатель может добавить понятные описания эндпойнта, параметров или структуры данных запроса, всего того же самого для ответа, пред- и постусловий вызова. Ещё очень помогают хорошие примеры.
Во-вторых, документация по API состоит не только из автогенерированной странички. Ещё можно написать руководство по написанию первой программы (tutorial) и инструкции по решению конкретных задач (how-to).
"Во вторых" - это уже devguide.
L
Именно это мне на днях втолковывали коллеги-программисты на кофепоинте, мол, идеальный код в комментариях не нуждается
Лень иногда порождает интересные теории;)
Читал на хабре пост, в котором говорилось, что генерация доки из комментариев - зло, потому что разработчик может поменять код, но забудет поменять комментарии и документация станет не актуальной)
Правда в этом же посте приводился интересный аргумент про то, что лучшая документация для кода - это тесты, читая которые становится понятно, что он делает.
Читал на хабре пост, в котором говорилось, что генерация доки из комментариев - зло, потому что разработчик может поменять код, но забудет поменять комментарии и документация станет не актуальной)
Правда в этом же посте приводился интересный аргумент про то, что лучшая документация для кода - это тесты, читая которые становится понятно, что он делает.
NV
Aleksandra
Добрый день.
Подскажите, пожалуйста, какая обычно зарплата у технических писателей на время стажировки?
Так же интересует, по каким критериям оценивается уровень технических писателей.
Гугл конечно, в помощь)
Но мне важно знать более экспертное мнение.
Подскажите, пожалуйста, какая обычно зарплата у технических писателей на время стажировки?
Так же интересует, по каким критериям оценивается уровень технических писателей.
Гугл конечно, в помощь)
Но мне важно знать более экспертное мнение.
Выяснил, что у нас в mail.ru зарплата стажёра примерно соответствует рыночной ставке джуна. Но стажировка — только для студентов.