Образец Технической Документации
Акт приема-передачи технической документации по договору подряда на содержание МКД Сущность акта приема-передачи технической документации по договору подряда на содержание МКД Для содержания общего имущества многоквартирного дома (МКД) собственники заключают с управляющими компаниями либо иными организациями договора подряда. Для выполнения подрядных работ, включающих в себя техническое обслуживание, санитарное содержание, текущий либо капитальный ремонт, благоустройство, подрядчику требуется множество сведений, содержащихся в технической документации.
ЧАСТНОЕ ТЕХНИЧЕСКОЕ ЗАДАНИЕ НА ПОДСИСТЕМУ УПРАВЛЕНИЯ ПЕЧАТЬЮ. СТРУКТУРНАЯ СХЕМА. Предлагаемый пример проектной документации реально разработанного и внедренного. На основе выданного Заказчиком технического задания, которое также приведено ниже. Документация на автоматизированные измерительно-информационные системы коммерческого учета электроэнергии (АИИС КУЭ). Комплекты документов на автоматизированные измерительно-ниформационные системы коммерческого учета электроэнергии (АИИС КУЭ), разработанные в разное. Образец договора на оказание сметно-технических. Сметной документации. Опубликованы документы, выполненные компанией «Техническая документация» в разное время в интересах различных заказчиков. Данные о заказчиках и исполнителях работ, шифры тем, реквизиты договоров, децимальные номера и пр. Изменены.Все документы боевые, щед.
Поэтому на время действия договора подряда заказчик и передает данные документы подрядчику. Передача технической документации на многоквартирный дом и иных связанных с содержанием общего имущества осуществляется по акту приема-передачи, который должен включать в себя сведения о дате и месте его составления и перечень передаваемых документов. Данный документ является приложением и неотъемлемой частью заключенного договора подряда на содержание МКД, составляется в произвольной письменной форме и скрепляется подписями представителей подрядчика и выборного лица жильцов МКД. После подписания акта приема-передачи ответственность за сохранность переданной технической документации переходит к подрядчику. Содержание акта-приема передачи технической документации В акте отражается список документов, которые передаются подрядчику по условиям заключенного договора подряда:.
техническая документация на многоквартирный дом ( тех.паспорт, акты осмотров, документы о приемке результатов работ после текущего либо капитального ремонта и т.д.);. другие документы, связанные с управлением МКД (кадастровая выписка, проектная документация, акт освидетельствования скрытых работ и прочее).
По каждому виду передаваемой документации указывается количество листов, что передается: оригинал/копия, примечания. Имеющиеся разногласия по количественному и (или) качественному составу документации на многоквартирный дом, подлежащей передаче, необходимо отразить в акте приема-передаче. № п/п Наименование документа Количество листов Примечания I.
Техническая документация на многоквартирный дом 1. Технический паспорт на многоквартирный дом с экспликацией и поэтажными планами (выписка из технического паспорта на многоквартирный дом) 2. Документы (акты) о приемке результатов работ по текущему ремонту общего имущества в многоквартирном доме 3. Документы (акты) о приемке результатов работ по капитальному ремонту общего имущества в многоквартирном доме 4.
Акты осмотра,проверки состояния (испытания) на соответствие их эксплуатационных качеств обязательным требованиям безопасности 4.1. Инженерных коммуникаций 4.2. Коллективных (общедомовых) приборов учета 4.3. Общих (квартирных) приборов учета Для определения объемов коммунальных ресурсов всеми потребителями в коммунальной квартире 4.4. Индивидуальных приборов учета Для определения объемов коммунальных ресурсов потребителями, проживающими в одном жилом помещении 4.5. Механического борудования 4.6.
Электрического оборудования 4.7. Санитарно- технического оборудования 4.8. Иного обслуживающего более одного помещения в многоквартирном доме оборудования 4.9. Отдельных конструктивных элементов многоквартирного дома (крыши, ограждающих несущих и ненесущих конструкций многоквартирного дома, объектов, расположенных на земельном участке, и других элементов общего имущества) 5. Инструкция по эксплуатации многоквартирного дома по форме, установленной федеральным органом исполнительной власти (для домов, вводимых в эксплуатацию с ) Содержит рекомендации застройщика (подрядчика), проектировщиков по содержанию и ремонту общего имущества, сроки службы его отдельных частей II. Иные связанные с управлением многоквартирным домом документы 6. Кадастровая карта (план) земельного участка 7.
Документы, в которых указываются содержание и сфера действия сервитута, с приложением заверенного соответствующей организацией (органом) по государственному учету объектов недвижимого имущества плана, на котором отмечена сфера (граница) действия сервитута, относящегося к части земельного участка, и документы, подтверждающие государственную регистрацию сервитута в ЕГРП 8. Проектная документация на многоквартирный дом, в соответствии с которой осуществлено строительство (реконструкция) многоквартирного дома 9.
Акт приемки в эксплуатацию многоквартирного дома 10. Акты освидетельствования скрытых работ 11. Протокол измерения шума и вибрации 12. Разрешение на присоединение мощности к сети энергоснабжающей организации 13. Акты разграничения эксплуатационной ответственности инженерных сетей электроснабжения, холодного и горячего водоснабжения, водоотведения, теплоснабжения, газоснабжения с ресурсоснабжающими организациями 14. Акты установки и приемки в эксплуатацию коллективных (общедомовых) приборов учета 15.
Паспорта на приборы учета, механическое, электрическое, санитарно-техническое и иное обслуживающее более одного помещения в многоквартирном доме оборудование 16. Акты передачи управляющей организации комплектов проектной документации и исполнительной документации после приемки многоквартирного дома в эксплуатацию 17. Письменные заявления, жалобы и предложения по вопросам качества содержания и ремонта общего имущества в многоквартирном доме и предоставления коммунальных услуг За год, предшествующий передаче документации 18. Журналы (книги) учета заявлений, жалоб и предложений по вопросам качества содержания и ремонта общего имущества в многоквартирном доме и предоставления коммунальных услуг 19. Иные связанные с управлением многоквартирным домом документы.
Введение Написание технического документа — трудное дело. Чтение плохо написанного технического документа является более трудным и, вероятно, более болезненным делом, чем его написание. Требуется большая работа, чтобы создать ясное, точное, интересное техническое описание. Поэтому, чтобы сделать жизнь хоть немного проще для всех участвующих сторон, я хотел бы поделиться с вами семью правилами, которым я следую, создавая техническую документацию. Эти правила — не моё собственное изобретение.
Скорее, я просто сформулировал их из того опыта, который появился благодаря общению со многими талантливыми техническими и литературными редакторами за более чем десять лет работы. Всё, что я понял в этом деле, сформировалось потому, что другие показали мне путь. У меня не находится достаточно слов, чтобы выразить им в полной мере мою благодарность. Надеюсь, после прочтения этой статьи в вашем арсенале появятся некоторые новые инструменты, которые помогут вам создавать технические документы на новом уровне качества: более ясные, более привлекательные, менее путанные и намного более интересные для чтения. Также я добавил — без всяких каких-либо дополнительных требований к вам, как потребителю, бонус в конце статьи: описание процесса, используемого мною для создания технического описания.
Итак — эти 7 правил:. Скука убивает. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд. Пишите в соответствии с правильно сформированной структурой. Избегайте неоднозначных местоимений.
Ясность = иллюстрации + слова. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример. Не опасайтесь переделок 1. Скука убивает Это правило является, по-видимому, самым трудным для формализации и самым важным по необходимости соблюдения.
В современном мире интернета действует много сил, борющихся за внимание вашего читателя. Скучное стандартное описание работать не будет. При любых обстоятельствах ваш читатель желает, чтобы было увлекательно и информативно. Поэтому, если ваш текст неясный или неинтересный, то читатель просто щёлкнет пресловутую кнопку «Далее» и перейдёт на другую веб-страницу или на другую ТВ-программу или на свою страницу в Фейсбуке. Самый простой путь, который я нашёл для пробуждения интереса у читателя, состоит в том, чтобы интересно было мне самому. Я всегда прилагаю значительные усилия, чтобы написать такую статью, которую сам хотел бы прочитать. Я стремлюсь получать удовольствие от того, что пишу.
Если мне скучно, то заскучает и читатель. Если я запутался, то запутается и читатель. Если меня не волнует рассматриваемая тема, то читатель, тем более, не взволнуется.
Всё очень просто! Мне нравится юмор, поэтому я стараюсь сделать мои литературные технические «творения» забавными, но, конечно, без ущерба для ясности. Пытаюсь разговаривать с читателем, а не поучать его. Пишу о делах, которые, действительно, имеют значение для меня. Широко использую иллюстрации, чтобы предотвратить неясность для читателя. И снова, всегда стараюсь сделать процесс чтения увлекательным. Я всегда помню, что пишу в конкурентной среде.
Имеется множество контента, стремящегося привлечь внимание читателей. Таким образом, мой совет по правилу № 1: если ваши тексты будут интересны вам, то они будет интересными и для читателя. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд Техническая документация полностью завязана на последующее поведение читателя. Читатель затрачивает своё время на чтение вашего творения, потому что он или она имеет намерение сделать что-то после завершения процесса чтения. Этим «что-то» может быть, остановка или разработка. Важно помнить, что читатель использует ваше описание как средство для выполнения другого процесса.
Ваш труд является неким проводником к дальнейшему вполне определённому поведению. Поэтому чрезвычайно полезно для вас чётко определиться, какие действия вы ожидаете от читателя после завершения процесса чтения. Изложите ваше намерение с самого начала. Не оставляйте читателя гадать. Ваше заявление может быть простым и очевидным, как, например: «после прочтения данной статьи вы сможете впишите свой вариант». Если вы определились с действиями, ожидаемыми от читателя после прочтения, то процесс написания будет для вас легче с самого начала.
Пишите в соответствии с правильно сформированной структурой Хорошо сформированная структура является тем остовом, вокруг которого растёт ваш документ. Подготовка технического документа без использования некоторой структуры равносильна попытке ориентироваться в (469 станций!) без схемы. Вы можете оказаться где угодно, но это «где угодно» может оказаться совсем не тем местом, куда вы предполагали попасть.
Написание технической документации в соответствии со структурой не означает увеличение объёма работы. Наоборот, нагрузка уменьшается. Работая со структурой, вы знаете, откуда вы выходите и куда собираетесь прийти. Имеются два правила структурирования, которые я всегда использую: 1.
Раздел подуровня требует наличия, как минимум, одной позиции. На каждом уровне структуры должно быть, как минимум, два предложения. Хотелось бы уточнить. Листинг 1 внизу является примером структуры, которая нарушает первое правило: раздел подуровня требует наличия, как минимум, одной позиции. Листинг 1: неправильно сформированная структура 1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка 1.1. Шаги, требуемые для приготовления шипучего напитка 1.1.1.
Подготовка ингредиентов 1.1.2. Смешивание ингредиентов шипучего напитка 1.1.3. Подача шипучего напитка Обратите внимание, что в листинге 1 уровень 1 имеет одиночный подуровень: ' 1.1. Шаги, требуемые для приготовления шипучего напитка'. Такая структура является нарушением первого правила. Чтобы подуровень был правильно сформирован, в разделе должна быть, как минимум, ещё одна позиция. Другими словами, это значит, что на любом данном уровне должно быть, как минимум, два подуровня.
Посмотрите листинг 2 внизу. Обратите внимание, что у уровня 1 теперь имеются три подуровня, из которых раздел «Смешивание ингредиентов шипучего напитка» содержит позиции. Одиночный уровень «Шаги, требуемые для приготовления шипучего напитка» удалён. Может возникнуть вопрос: «Где раздел Шаги, требуемые для приготовления шипучего напитка»? Видно, что этот раздел теперь не является позицией структуры, а перешёл в контент исходного раздела, как показано в листинге 2 внизу. Листинг 2: правильно сформированная структура, нарушающая правило двух предложений 1.
Приготовление апельсиново-клюквенно-мандаринового шипучего напитка Раздел внизу описывает процесс, который надо соблюсти для приготовления апельсиново-клюквенно-мандаринового шипучего напитка. Подготовка ингредиентов 1.2. Смешивание ингредиентов шипучего напитка 1.3. Подача шипучего напитка Обратите внимание, что, хотя листинг 2 демонстрирует структуру с правильно сформированным подуровнем, в контенте раздела уровня 1 имеется только одно предложение. Присутствие одного единственного предложения в контенте раздела структуры нарушает второе правило структурирования — ' На каждом уровне структуры должно быть, как минимум, два предложения'. Листинг 3 показывает тот же текст, но изменённый с целью обеспечить выполнение правила двух предложений.
Листинг 3: правильно сформированная структура, выполняющая правило двух предложений 1. Приготовление шипучего апельсиново-клюквенно-мандаринового напитка Апельсиново-клюквенно-мандариновый шипучий напиток может доставить большое удовольствие в жаркий летний день. Напиток состоит из природных компонентов без искусственных ароматизаторов. Апельсиново-клюквенно-мандариновый шипучий напиток не только вкусный, но и чрезвычайно полезный!
Разделы внизу описывают процесс, который надо соблюсти для приготовления апельсиново-клюквенно-мандаринового шипучего напитка. Подготовка ингредиентов 1.2. Смешивание ингредиентов шипучего напитка 1.3. Подача шипучего напитка Почему я так беспокоюсь о правильной структуре и о, по крайней мере, двух предложениях на каждом уровне?
Во-первых, соблюдение правила подуровня побуждает меня быть предельно чётким в логической сегментации моего труда. Следование правилу подуровня способствует также тому, что мой текст соединяет мои идеи с общей линией, которая имеет смысл и легко прослеживается. Во-вторых, правило двух предложений требует от меня написать текст, который является привлекательным, подробным и целесообразным.
При записи в «одно предложение» нередко теряются подробности. И, если не рассматривать афоризмы, текст в «одно предложение» — не самое интересное чтение.
Избегайте неоднозначных местоимений Неоднозначное использование местоимений является, вероятно, самой типичной причиной путаницы в практике подготовки технических описаний. Рассмотрим абзац в листинге 4.
Листинг 4: абзац с неоднозначными местоимениями Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья показывает, чем они являются и как их использовать. Данный абзац выглядит, возможно, несколько комично, но он иллюстрирует некоторые важные точки.
Во-первых, абзац пытается поставить вас на место, которое занимает читатель. Читатель желает понять, что происходит, но он незнаком с используемыми терминами. А поскольку термины непонятны, то читатель ощущает себя некомпетентным и потому уязвимым. Читателю нужна новая информация — он или она желает стать умнее. Но читатель также немного беспокоится. Допущение собственной некомпетентности, даже перед самим собой, даже на подсознательном уровне — может быть ему неприятно.
Читатель болезненно чувствителен к пониманию представляемого материала. Понятия и слова, которые вы, лицо пишущее, считаете само собой разумеющимися, могут быть полностью чуждыми читателю. Одно плохо объяснённое понятие или одно слово, использованное без надлежащего разъяснения, могут подтолкнуть читателя прекратить чтение. Применительно к абзацу вверху я не удивлюсь, если вы спросите: «Что это за штука „Трафальгабор“? А что такое „Вибитата“?
О чём, вообще, этот абзац? О том, как использовать Трафальгаборы? Или о том, как использовать Вибитаты?
Или о том, как использовать и те, и другие? Бред какой-то. Вернусь я лучше на свою страницу в Фейсбуке». Если читатель при чтении вашего описания вынужден тратить время на выяснение, что же вы пытаетесь ему сообщить, то мало того, что информативный поток будет нарушен, но и читатель, скорее всего, будет запутан. Как только вы привели читателя в замешательство, вы его потеряли. Всё другое в мире, направленное на привлечение внимания вашего читателя, становится для него более притягательным, чем ваше творение. Щелчок по кнопке «Далее» — и ваша работа остаётся непрочитанной.
В листинге 4 замешательство порождается неоднозначным использованием местоимения «они» во втором предложении. К чему относится здесь «они» — к Трафальгаборам, Вибитатам или к обоим? Помните, что читатель ничего не знает, что такое Трафальгаборы или Вибитаты. 1 внизу.) Рис. Использование неоднозначных местоимений запутывает техническое описание Решение проблемы простое. Посмотрите листинг 5 внизу.
Неоднозначное местоимение удалено. Ясность восстановлена. Листинг 5: устранение неоднозначных местоимений Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья рассказывает, что такое Трафальгаборы и как их использовать. Неоднозначное использование местоимений ведёт к техническому описанию, приводящему в замешательство. Ясность = иллюстрации + слова Посмотрите на фотографию внизу. Скажите, если сможете, о чём это фото?
Предмета
Я не удивлюсь, если вы будете немного растеряны. Эта фотография, действительно, озадачивает. Вы знаете все отдельные компоненты, но вам неясно, что они все вместе значат.
Такова природа любой иллюстрации. Картинке без слов не хватает контекста.
При обращении к иллюстрациям читателям требуется контекст, чтобы внести ясность. Недопустимо, чтобы читатель напрасно тратил время или усилия, пытаясь выяснить, о чём же рассматриваемая графика. Самым лёгким путём устранить неясность с иллюстрациями является обеспечить их надписями. Посмотрите на рис.
Он представляет собой то же самое фото. Но здесь уже нет вопроса, о чём оно. Инструменты и ингредиенты, требуемые для приготовления апельсиново-клюквенно-мандаринового шипучего напитка Применительно к техническим описаниям я считаю полезным все иллюстрации снабжать пронумерованными описательными надписями. Не помещайте надписи, содержащие только цифры. Используйте в надписи, как цифры, так и описательный комментарий. Также не допускайте появления изолированных иллюстраций. Изолированной иллюстрацией считается такая, которая расположена в техническом описании, но ссылка на которую в тексте отсутствует.
Вставляя иллюстрацию в ваше описание, следите за тем, чтобы сослаться на неё в тексте указанием её номера и таких слов как «выше», «вверху», «ниже», «внизу». Недопустимо вынуждать читателя при чтении вашей работы тратить время на привязку иллюстрации к тексту или на её поиск в описании. Если вы добавляете в текст, скажем, «Рис. 4», то убедитесь, что где-то в тексте сказано что-то вроде «см. Примечание: глаз привлекают изображения Десять лет назад я работал в группе, которая писала пользовательское руководство (под типографское издание) для очень, очень большого изготовителя компьютеров. Все руководства подвергались формальному количественному исследованию на удобство пользования. Тогда от специалистов по взаимодействию с пользователем я узнал, что, когда человек читает руководство, глаз его идёт сначала к изображениям.
Лишь затем читатель смотрит на текст вокруг этого изображения. Поэтому авторы того руководства пытались обеспечить, чтобы на каждой его странице была хотя бы одна картинка.
Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример, логическую иллюстрацию и пример Понятия трудны для понимания — и это то, почему они называются «понятиями». Поэтому, когда мне приходится писать о каком-то общем положении — будь то, компонент методики кодирования или полнофункциональная платформа программного обеспечения, я использую следующий подход в моём описании: понятие — логическая иллюстрация — пример. Я никогда не пытаюсь ввести какое-либо понятие без подкрепления логической иллюстрацией и дальнейшим примером. Применим это правило для описания понятия элементарной алгебры. Понятие «транзитивность отношения равенства» представляет собой следующее: если A = B и B = C, то A = C; Теперь приведём логическую иллюстрацию, описывающую это понятие (см.
Транзитивность отношения равенства является фундаментальным принципом элементарной алгебры Листинг 6 ниже показывает несколько конкретных примеров для закрепления понимания рассматриваемого положения. Листинг 6: некоторые конкретные примеры транзитивности отношения равенства. Если 7 = 3 + 4 и 3 + 4 = 5 + 2, то 7 = 5 + 2;. Если 12 + 5 = 7 + 10 и 7 + 10 = 6 + 11, то 12 + 5 = 6 + 11;.
Если x + y = z и z = 2a, то x + y = 2a. Таким образом, правило соблюдено. Мы представили понятие «транзитивность отношения равенства», проиллюстрировали его описательным рисунком и подкрепили примерами. Теперь рассмотрим понятие, которое ближе к разработке программного обеспечения и несколько труднее для понимания. Таким понятием является (система автоматизированной сборки проектов). Пример 1 ниже представляет рассматриваемое понятие и даёт логическую иллюстрацию, описывающую это понятие.
В конце представлена ещё одна иллюстрация, показывающее конкретное использование POM-файлов в ситуации наследования. Пример 1: выдержка из технического описания наследования моделей объектов проекта (POM) в Maven (система автоматизированной сборки проектов) Представление наследования POM-файла -файл является XML-файлом, используемым для описания -проекта и для работы с этим проектом.
Можно задать, чтобы некоторый Maven-проект наследовал настройки из отдельного родительского POM-файла. Способность наследовать настройки из родительского POM-файла называется POM-наследованием. Вы используете элемент в вашем POM-файле, чтобы задать родительский POM-файл, из которого должно произойти наследование настроек. 4 ниже показывает иерархию некоторого условного проекта, являющуюся примером задания мастер-файла РОМ, из которого другие РОМ-файлы могут наследовать общие настройки.
Можно назначить мастер-файл РОМ, из которого будет происходить наследование общих настроек Рис. 5 ниже показывает содержание POM.xml-фалов для Maven-проектов stooges-web, stooges-api и stooges-dal. Каждый проект сконфигурирован на использование элемента для наследования настроек из stooges-project. Использование элемента для управления Maven-проектом с целью наследования настроек из внешнего РОМ-файла Пример выше опирается, в основном, на рисунки, чтобы обеспечить логическую иллюстрацию и показать конкретное использование рассматриваемого понятия. Подготовка интересных, привлекательных и точных иллюстраций и примеров является трудной задачей, но усилия стоят того. Создание множества иллюстраций для технического текста и примеров кода требует времени не меньше, чем написание самого текста. Соответственно я планирую моё время, чтобы выполнить работу в срок.
Итак, если требуется предельно ясно представить какое-то понятие, то необходимо включить в текст иллюстрации и примеры. Не опасайтесь переделок Редко удаётся написать хороший технический текст с первой попытки. Освоение темы, организация подходов и нахождение формы ясного и точного представления идей требует много времени и усилий. Поэтому не стесняйте себя ожиданием, что всё получится прямо с первого раза. Лучше планируйте пройти, как минимум, через три версии вашего творения. Первая версия представляет собой просто некоторый набор слов в печатном виде, давая вам возможность осознать ваши намерения.
Вторая версия уже придаёт вашей работе ясность и точность. Затем, когда все факты в тексте проверены, иллюстрации выверены и структура логично выстроена, можно подготовить третью версию, которая будет привлекательной и своеобразной. Можно сказать об этой работе, перефразируя известную: «Написание технического текста — это на 10% литературное творчество и на 90% переработка!» Обещанный бонус Теперь, когда вы знаете 7 правил для создания технической документации мирового класса, я хотел бы поделиться с вами изложением процесса, который я использую при подготовке технических текстов. Здесь немного, но по существу.
Я называю этот процесс — ' «7 шагов создания технического документа». Составляю структуру, как минимум, до второго уровня (если удаётся, то и до третьего); 2. Добавляю иллюстрации в структуру для каждого понятия; 3. Делаю подписи под иллюстрациями; 4. Пишу текст в соответствии со структурой, соблюдая правило двух предложений и подстраивая структуру под текст; 5.
Редактирую, переделываю; 6. Отправляю результат специалисту по рассматриваемой теме на рецензирование (специалистом по рассматриваемой теме является лицо, которое в состоянии выявить неточности и неясности в описании); 7.
Снова редактирую работу на основе отзыва рецензента (рецензентов). И вот они у вас: 7 правил, 7 шагов. Кому-то надо больше? Теперь, когда вы знаете все мои приёмы, двигайтесь свободно вперёд и делайте мир более правильным, привлекательным, ясным и интересным местом для жизни. Он заслуживает таких усилий.
Метки:. Добавить метки Пометьте публикацию своими метками Метки лучше разделять запятой. Например: программирование, алгоритмы. Есть один большой производитель ПО, который почему-то практически не вставляет изображения в документацию. Ненавижу его за это. Всё пишет словами, хоть и с пунктами и подпунктами, как вы говорите.
Всё гадаю почему он так делает. Документация многоязычная. Изображение всегда содержит буквы, которые должны быть переведены. Но средство перевода не имеет возможностей управления изображениями, как объектами которые зависят от языка. Кстати, в данной статье не переведена картинка «Рисунок номер один».
Мне кажется это не айс для статьи. Изображение может содержать скриншоты интерфейсов программных средств, а они зависят от локализации, операционной системы, темы оформления итд итп. Кстати, была у нас тут была задача у технописателей перешотить скриншоты в теме оформления, которая по умолчанию включена у пользователей.
А у технописателей обычно была другая. Процесс перевода устроен так, что сначала разрабатывается исходная документация, потом отдается переводчику. Переводчик не имеет доступа к приложению и не может переснять скриншот на нужном ему языке. Не вставлять изображения — один из способов не создавать проблем. Кстати, именно поэтому я некоторых случаях избегал вставлять таблицы к документам по ГОСТу (продолжение таблицы будь оно проклято, ругался с проверяющими — без толку).
По моему мнению, нельзя пользоваться вордом для писания документации. Многие вики-системы имеют бедные инструменты по работе с таблицами и рисунками. И от этого качество документации в итоге тоже страдает. Кстати, в документации от этого разработчика ПО и таблиц меньше чем хотелось бы. Всё больше списки.
Есть один большой производитель ПО, который почему-то практически не вставляет изображения в документацию. Ненавижу его за это. Всё пишет словами, хоть и с пунктами и подпунктами, как вы говорите. Всё гадаю почему он так делает.
Ответ очень простой — ему ммм безразлично, качество документации, производитель Большой — от него никто никуда не денется. Вот если бы это был стартап, особенно с существенными вложениями, то и таблицы бы переделывали и скриншоты бы переснимали и даже кейсы бы переписывали с учётом страны/языка. Вы абсолютно правы. Но, к примеру, у меня 99% всех картинок — это скриншоты, а не схемы. Для того, чтобы поддерживать это добро в актуальном состоянии, мы пользуемся обратной связью и регулярно просматриваем свои документы (см.
Комментарий ). В некоторых случаях можно заранее предугадать, что скриншот устареет через некоторое время, например, если в скриншоте виден номер версии продукта. Такие скриншоты мы помечаем специальным флагом. Перед выпуском новой версии технический писатель выбирает из БД те картинки, которые содержат устаревший номер версии и снимает эти картинки по-новой. С моей точки зрения правилами хорошей документации должны быть:. Обязательное наличие канала обратной связи для улучшения документации. Большое количество примеров наиболее распространенных use-case'ов.
Пример Технической Документации
Документацию регулярно нужно перечитывать (одним сотрудником раз в месяц, чтобы избежать замыленности внимания). Возникающие вопросы тут же пояснять. Качественные цветные графики, иллюстрации. С этим чаще всего бывают проблемы. Взгляните хотя бы вот. Полная воспроизводимость руководства к действиям.
Состав В Картинках
За этим тоже нужно регулярно следить. Я эту тему уже затрагивал. Добавлю ещё одно, крайне на мой взгляд, важное правило (получилось в стиле zen): Лучшая документация — ненужная документация Смысл в том, что с большинстве случаев пользователь должен получать решения без обращения к документации, в идеале просто нажимать кнопку «сделать хорошо». Конечно, это требование не столько к документации, сколько к самому продукту, но здесь документация играет роль своеобразного индикатора — чем чаще она требуется, тем сложнее приложение (в смысле «усложнено»). Причём особенно играет этот фактор на этапе вхождения нового пользователя.