Size: a a a

technicalwriters

2020 July 17

CD

Constantine Drozdov in technicalwriters
Vladimir Izmalkov
качественную документацию по ГОСТ любо-дорого читать. Просто ГОСТы в оформлении локументации не всегда нужны. Но в сложных областях, где работают профессионалы - стандартизация очень важна.
Именно так. Наличие стандарта значительно улучшает ваш паттерн-матчинг (можно бюллетень как это нормально по-русски? :)). Требование абсолютной жесткости при этом не нужно, нужно только условно говоря писать заявление о передаче почки нуждающемуся за каждое отклонение от стандарта, которое вы умышленно допускаете.
источник

VI

Vladimir Izmalkov in technicalwriters
загонять документацию в рамки некоего стандарта – все равно что усреднять. Супер крутой документации стандарт только мешает быть максимально удобной, но вот супер унылую документацию стандарт может вытащить до удовлетворительного уровня, если ему следовать.
источник

VI

Vladimir Izmalkov in technicalwriters
жаль, что ГОСТы сильно устарели, а новые пишут уже не так фундаментально и правильно =)
источник

CD

Constantine Drozdov in technicalwriters
В общем, кажется, мы спорим об одном и том же. У вас должен быть соответствующий уровень квалификации, чтобы отклоняться от стандарта, вы должны быть способны предложить вариант лучше, и очень хорошо понимать его последствия
источник

VI

Vladimir Izmalkov in technicalwriters
Constantine Drozdov
В общем, кажется, мы спорим об одном и том же. У вас должен быть соответствующий уровень квалификации, чтобы отклоняться от стандарта, вы должны быть способны предложить вариант лучше, и очень хорошо понимать его последствия
Согласен
источник

CD

Constantine Drozdov in technicalwriters
Vladimir Izmalkov
Согласен
Кажется, нам остаётся собрать нужных людей вместе и развести немного бюрократии, чтобы каждый подобный случай обсуждался и, если можно улучшить стандарт, улучшать стандарт. Мы получим хорошо работающую систему (пусть у неё есть известные недостатки), которой при этом очень сложно изначально самоорганизоваться
источник

FM

Fox Mulder in technicalwriters
А потом выпустили документацию, читать которую будет скучно )
Галочку поставили, проект сдали. А о пользователях забыли.
источник

CD

Constantine Drozdov in technicalwriters
Fox Mulder
А потом выпустили документацию, читать которую будет скучно )
Галочку поставили, проект сдали. А о пользователях забыли.
Ну так предлагайте новые обои
источник

FM

Fox Mulder in technicalwriters
При этом все забывают о главном - для чего нужна документация.
А нужна она только для одного - помочь юзверю овладеть продуктом.
источник

VI

Vladimir Izmalkov in technicalwriters
А вы не слышали анекдот?
Собрались как-то ученые и давай обсуждать: Безобразие! У нас 14 разных стандартов в одной области, которые противоречат друг другу!
Побузили, составили рабочую группу и разошлись.
Через год собрались опять:
Безобразие! У нас 15 разных стандартов в одной области, которые противоречат друг другу!
источник

CD

Constantine Drozdov in technicalwriters
Fox Mulder
При этом все забывают о главном - для чего нужна документация.
А нужна она только для одного - помочь юзверю овладеть продуктом.
Почему вы считаете требование единообразия противоречащим требованию разнообразия?
источник

FM

Fox Mulder in technicalwriters
Constantine Drozdov
Ну так предлагайте новые обои
Да всё давно придумано до нас. Есть документация на АПЛ и есть документация на софт.
Первая должна быть написана в строгом соответствии со стандартами, а вторая - так, что бы было понятно и приятно.
источник

VI

Vladimir Izmalkov in technicalwriters
Fox Mulder
Да всё давно придумано до нас. Есть документация на АПЛ и есть документация на софт.
Первая должна быть написана в строгом соответствии со стандартами, а вторая - так, что бы было понятно и приятно.
а лучше выпускать срау обе версии - на АПЛ тоже ведь люди работают
источник

CD

Constantine Drozdov in technicalwriters
Fox Mulder
Да всё давно придумано до нас. Есть документация на АПЛ и есть документация на софт.
Первая должна быть написана в строгом соответствии со стандартами, а вторая - так, что бы было понятно и приятно.
И если вы мне документацию SDK приложите в нефиксированной структуре, я очень странно на вас посмотрю
источник

CD

Constantine Drozdov in technicalwriters
И вот мы сейчас переоткроем одну очень большую истину, что документация может быть "знаете ли вы", а может быть рабочим инструментом, и во втором случае я буду скучать от любой попытки выйти из рамок
источник

FM

Fox Mulder in technicalwriters
Constantine Drozdov
И если вы мне документацию SDK приложите в нефиксированной структуре, я очень странно на вас посмотрю
Есть боль - сделать описание API в docx
источник

FM

Fox Mulder in technicalwriters
источник

CD

Constantine Drozdov in technicalwriters
Fox Mulder
Есть боль - сделать описание API в docx
Не вижу существенной проблемы в этом
источник

FM

Fox Mulder in technicalwriters
Constantine Drozdov
Не вижу существенной проблемы в этом
Можно пример вашего описания API в ворде? Если вы не видите проблемы?
источник

FM

Fox Mulder in technicalwriters
Я вот вижу в этом огромную проблему, т.к. переложить текст в ворд нет проблем, проблема есть в невозможности использования оного
источник