Техническая документация Техническая информация: Как написать один

Question

Люди,

Каков наилучший способ исследования и представления технического документа? Я не имею в виду формат, обзор, разделы и т. Д.

Я никогда не писал один - и мне интересно, если белая бумага должна быть очень и очень общий (концептуальный) или специфические (например, в пользу конкретного инструмента/методологии)

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

Answer 1

Да, попробуйте прочитать другие технические белые документы. Но не просто читайте белую бумагу. Читайте лучшие. Вы можете обычно определить, что является «лучшим», проверяя, сколько раз была процитирована бумага (один веб-сайт, на который я иду, - cite seer и google scientar). Некоторые общие руководящие принципы будут следующими:

1. Постарайтесь быть прямо к делу, не бить вокруг куста.
2. Используйте свои акронимы последовательно.
3. Воспользуйтесь возможностью, чтобы изложить слабые стороны предыдущих методов, так как это показывает, что вы пытались пересмотреть/опросить другие методы.
4. Технический документ должен быть очень конкретным. Укажите, как работает ваш метод, точно укажите, как вы проводите эксперименты (чтобы другие могли повторять ваши эксперименты), точно укажите ваши результаты (много графиков было бы неплохо) и, наконец, завершите их в 40-60 слов или около того.
5. Акцент на новые вещи (материал, который вы предлагаете) и меньше на старых, которые были бы (это был бы ваш фон). Сделайте различие понятным.
6. Как правило, вы не включаете исходный код в свою бумагу. Если вам необходимо, опубликовано на веб-странице вместе со ссылками на ваш документ.

P/S: Мой совет немного предвзято относится к академической работе. Но я думаю, что это должно применяться в вашем случае.

Answer 2

Мои +0,02:

Почитаю пару, и попытаться сделать Mindmaps пытаются придумать идеи о том, как они выглядят.

После того, как вы сделали этот анализ, вернитесь назад и выберите разделы, которые вам понадобятся. В частности, build ANOTHER карта разума с вашей структурой документа.

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

Answer 3

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

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

Answer 4

Это звучит немного бесполезно, но белые документы поступают во всех формах, от очень специфических до очень общих. Определите, какова конечная цель. Вы пытаетесь что-то продать или описываете, как работает новый технический виджет, или описывают опыт? Кроме того, определите свою аудиторию, будь то деловые, технические, домашние и т. Д.

Осмотрите примеры - большинство крупных компаний (IBM и т. Д.) Имеют сотни на своем веб-сайте. Прочитайте несколько и посмотрите, что поражает вас как хорошие и плохие моменты.

Answer 5

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

Например, документ, посвященный теме R + D или представленный в академических кругах, или предназначенный для обеспечения концептуального эскиза какой-либо будущей работы, будет написан более пассивным голосом, почти Q + A. Обсуждение. Вы, вероятно, представите несколько идей и, возможно, будете их зависеть от того, что они не обязательно достигнут фиксированного вывода.

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

Единственное, что вы можете сказать в целом, это то, что этот процесс работает от неопределенного -> конкретного.

Answer 6

How to Write a White Paper – A White Paper on White Papers
Автор этой части также написал книгу:
Writing White Papers: How to Capture Readers And Keep Them Engaged