«Как писать технические документы? Комментарий удивителен. Статья «Как написать хороший дизайнерский документ» полна враждебности.
Я не уверен, что мои идеи устарели в новую эру Интернета. Кажется, что писать документы стало меньшинство. В любом случае выражайте свою точку зрения четко.
Все мнения в этой статье являются личными, и нет никакого «суждения», чтобы поделиться тем, что вы считаете правильным.
Закадровый комментарий: Материал в следующем тексте, скриншоты из раздела «Как писать техническую документацию? "В комментарии скрыты аватар и имя.
1. 
Как писать технические документы? «В комментариях наиболее близок пункт: не писать техническую документацию, потому что только так начальник не осмелится заменить ta случайно, сделав ta« незаменимым ».
Однако «незаменимость рабочего места»
не означает:
«Я закопал много скрытых ям. Только я знаю, где скрытые ямы, поэтому я незаменим».
Скорее, это означает:
«У меня есть основная конкурентоспособность, которой нет у других. Это может быть отношение, профессиональные способности или привлекательность».
Солнечная положительная энергия:
Усердно думая на рабочем месте и сохраняя свою «железную чашу для риса», «копая ямы», лучше усердно работать, чтобы повысить свою основную конкурентоспособность, чтобы у вас была возможность есть везде.
2. 
Вторая точка зрения: документ написан для других, для начальника, для клиента, для человека, который хочет общаться, и для человека, который хочет взять на себя проект. Участникам проекта не нужно писать документацию.
Зачем писать проектную документацию?
Для себя позвольте себе помочь себе подумать более ясно, прежде чем писать код;
для проектов обеспечьте согласованность информации, обеспечьте управляемость проекта и уменьшите риски проекта;
для команды обеспечьте осаждение и наследование знаний;
Сколько подсистем задействовано в проекте, сколько модулей задействовано в каждой подсистеме, каковы зависимости между модулями, сколько интерфейсов необходимо предоставить друг другу, каковы параметры каждого интерфейса, как взаимодействуют восходящие и нисходящие потоки в процессе реализации интерфейса и какие технические решения используются для базовой логики Поймите ... Все ли знают соответствующие технические специалисты?
Многие уверенные в себе боги технологий «думают», что понимают, но не понимают. На самом деле, они просто не понимают.
Многие «ясно говорят», но «нечетко написано» на самом деле не понимаются.
Только когда проект и техническая проблема описываются словами и логически, это означает, что реальное мышление ясно.
Голос за кадром: если вы попадете на бумагу, вы можете найти много проблем в дизайне.
Как документ обеспечивает согласованность информации и снижает риски проекта?
В качестве простого примера инженеру PHP необходимо предоставить интерфейс HTTP для получения информации о заказе, а затем его необходимо согласовать с инженером IOS / Android / FE, а также необходимо провести тестирование инженеру QA.
Разве не обязательно оформлять HTTP-интерфейс на бумаге?
http://daojia.com/order/getinfo?oid=${oid }
cookie: uid = $ {uid}
cookie: token = $ {token}
…
RESTFUL формат интерфейса, формат ввода и вывода, информация - PHP / IOS / Инженеры Android / FE / QA нуждаются в четкой информации, иначе связанные с этим совместные работы по отладке и тестированию НИОКР не будут выполняться. Нужно ли каждый раз сообщать эту информацию устно?
Через год после запуска проекта интерфейс необходимо обновлять итеративно. Вам нужно каждый раз проверять код?
Закадровый голос: заметки очень важны. Заметки и документы не конфликтуют. Они не решают одну и ту же проблему.
Солнечная положительная энергия:
Написание хорошей документации полезно для вас самих, для проекта и для команды. Почему бы не сделать это?
3. 
Третья точка зрения: некогда писать.
Бог справедлив, время экономится, тратьте больше времени на размышления о дизайне, кодирование определенно будет более плавным, может сократить много времени на общение / споры, может сэкономить много времени на дополнительную модификацию / совместную отладку / тестирование, вызванное изменениями программы , Что может сэкономить много времени при долгосрочном обслуживании.
Солнечная положительная энергия:
Я хочу заниматься спортом, но у меня нет времени.
Я хочу выучить английский, но у меня нет времени.
Я хочу написать хороший документ, но у меня нет времени.
У меня есть время читать «Моменты», заголовки, вибрато и сериалы про погоню.
Отвергните оправдания, действуйте сообща и напишите техническую документацию.
В-четвертых, 
есть и другая точка зрения: быстро меняются требования, быстро меняются решения, а документы пишутся медленно, поэтому писать документы бесполезно.
Обсуждая вопрос, сначала обсудите рациональность. Если это разумно, но есть трудности, тогда посмотрите на трудные решения. Обычно это должна быть такая логика, верно?
Потому что:
«Требования меняются быстро, решения меняются быстро, а документы пишутся медленно».
Итак:
«Написание документов бесполезно»
Сама логика неверна.
Нам (особенно техническому руководителю, имеющему право говорить и принимать решения), в первую очередь, не стоит об этом думать:
- Спрос постоянно меняется, разумно ли это?
- План всегда меняется, разумно ли это?
- Разумно ли писать документы медленно?
- Разумно ли отсутствие документации?
Разве вы не должны сначала задать себе эти вопросы.
Если вы думаете, что «написание документов идет медленно и неразумно», то не следует ли вам подумать об этом следующим образом:
почему пишут медленно? Это происходит из-за недостаточной готовности сотрудников, недостаточных способностей сотрудников, плохого использования инструментов или по другим причинам?
- Если желания недостаточно, как повысить желание сотрудников
- Если способности недостаточны, как улучшить способность персонала
- Если инструмент плохой, как оптимизировать эффективность инструмента
...
Существование может быть неразумным:
- «Рабство» существует тысячи лет, поэтому разумно ли быть рабом?
- «Общий спрос меняется, планы всегда меняются, а документации нет», но обязательно ли это разумно?
Солнечная положительная энергия:
Как технический руководитель, братья и сестры в вашей команде находятся в ужасном положении, но вы не действуете. Разве вы не чувствуете себя виноватым? Пожалуйста, действуйте в рамках своих возможностей, чтобы попытаться изменить необоснованный статус-кво и создать технологическую атмосферу.
V. 
Одна точка зрения: если другие не пишут, пишите сами и теряйте деньги.
Одна точка зрения: начальнику нужны документы, а фермерам кода - нет.
Одна точка зрения: зарплата такая низкая, не пишите, если повышают, пишите.
Одна точка зрения: написание документов - это достижение других.
Закадровый голос: комментариев слишком много, поэтому я не буду публиковать их один за другим. См. Непосредственно «Как писать технические документы?» "Комментарий внизу.
Статья «Как писать технические документы? ", большинство мнений в комментариях -" это бесполезно ", чего я никак не ожидал.
Голос за кадром: Надеюсь, все просто шутят надо мной, вместо того, чтобы так думать.
Думаю, даже то, на чем я всегда настаивал, верно?
В 2011 году, когда меня перевели на другую должность, я совершил серьезную «передачу модуля». Я разобрал и суммировал 13 модулей, за которые отвечал в то время. Я боялся, что после того, как я сменил работу, инженер, который занял эту должность, может не справиться с проектом и модулем, поэтому я чувствовал себя чрезвычайно виноватым.
Даже через несколько месяцев после передачи, если у коллеги, который взял на себя мой модуль, возникнут вопросы, я подойду к столу коллеги, чтобы ответить на вопрос коллеги.
конец:
Независимо от того, пишет кто-то документ или нет, я считаю, что это правильно, и я это сделаю.
Независимо от того, требуется ли документация другим руководителям, в моей команде я это сделаю.
По прошествии многих лет, возможно, вы обнаружите, что именно потому, что вы сделали выбор, отличный от других, вы стали отличным от других.
взаимное поощрение!
Технологии земляных работ архитектора
связанное предложение:
«Как писать технические документы? «
Спрос всегда меняется, это разумно?» 》
Исследование:
Ваш начальник делает что-нибудь необоснованное?