Како да напишете софтверска документација: 8 чекори

Добра софтверска документација - без разлика дали станува збор за документ со спецификација на барањата за програмери или тестери, технички документ за внатрешни корисници, прирачникот за користење на софтвер или програма поттикнува за корисниците - им помага на лицето кое работи со софтвер, да ги разбере своите карактеристични карактеристики и Функции. Следете ги советите - Како да напишете софтверска документација за технички и крајни корисници.

Чекори

Метод 1 од 2:

Пишување софтверска документација за технички корисници.

Еден. Утврди кои информации мора да се споменат. Документите за барањата на софтверот служат како упатство за дизајнери на кориснички интерфејс, програмери кои пишуваат код и тестери кои проверуваат дали софтверот работи на следниов начин. Точните информации зависи од самата програма, сепак, може да го вклучи следново:

Клучни датотеки во апликацијата. Овие може да бидат датотеки создадени од страна на тимскиот тим, бази на податоци предизвикани за време на операцијата на софтверот и програмите за услуги на трети лица.
Функции и потпрограми. Тука е индицирано дека секоја функција и потпрограм го прави, вклучувајќи влез и излезни вредности.
Софтверски променливи и константни и како се користат во апликацијата.
Општа структура на програмата. За апликации базирани на дискови, најверојатно ќе ви треба опис на поединечни блокови и програмски библиотеки, додека веб апликациите ќе имаат потреба од опис на страници кои користат датотеки.

Сликата насловена напишана софтверска документација Чекор 2

2. Одлучи колку документација треба да биде во програмскиот код и колку треба да се одвои. Колку повеќе техничката документација е креирана во програмскиот код, толку е полесно да го ажурира овој код како документација во врска со разни верзии на оригиналната апликација. Како минимум, документацијата во програмскиот код треба да ги објасни функциите, потпрограмите, софтверските константи и променливите.

Ако програмскиот код е прилично долг, може да се стави како референтна датотека во која можете да пребарувате по клучни зборови или патокази. Тоа ќе биде голем плус за апликации каде што логиката на програмата е поделена на многу страници и вклучува помошни броеви на датотеки, како во одредени веб апликации.

Некои програмски јазици, како што се Јава или нето рамка (Visual Basic.Нето, C #), имаат свои стандарди за код за документација. Во такви случаи, следете ги стандардните упатства - колку документација треба да бидат вклучени во програмскиот код.

Сликата насловена напишено софтверска документација Чекор 3

3. Изберете соодветна алатка. До одреден степен, ова е дефинирано со јазикот на кој е напишан кодот, било да е тоа C ++, C #, Visual Basic, Java или PHP - за секој има сопствена алатка. Во други случаи, алатката што се користи се одредува со видот на потребната документација.

Уредувач на текст "Microsoft Word" - алатка за создавање на одделни документи за текстуални датотеки кои ќе бидат едноставни и кратки. За долги текстуални датотеки, многу технички документирани програмери претпочитаат да ја изберат програмата Adobe FrameMaker.

Совет датотеки за документација на софтверски код може да биде напишана со користење на било која алатка, како што е Robohelp, Help и Manual, Doc-to-Help, Madcap Flare или "Helplogix".

Метод 2 од 2:

Пишување софтверска документација за крајните корисници

Еден. Идентификувајте комерцијални размислувања за вашата документација. Иако функционални причини за софтверска документација треба да им помогне на корисниците да разберат како да ја користат апликацијата, постојат и други причини, како што е помош во промовирањето на стоката на пазарот, подобрување на имиџот на компанијата и најважното, намалување на трошоците за техничка поддршка. Во одредени случаи, документацијата е потребна за да се усогласат со одредени правила и законски барања.

Во никој случај, програмската документација не треба да го замени дизајнот на лошиот интерфејс. Ако екранот на апликацијата бара многу објаснувачка документација, подобро е да го промените дизајнот на нешто поинтуитивно.

Сликата насловена напишана софтверска документација Чекор 5

2. Разбирање на публиката за која пишувате документација. Во повеќето случаи, корисниците на софтвер знаат малку за компјутерите во прилог на задачи за апликација. Постојат неколку начини за да се утврди како да се координираат нивните потреби со документација.

Погледнете ги професиите во сопственост на вашите потенцијални корисници. Системскиот администратор најверојатно ќе биде експерт за користење на софтверски апликации, додека операторот за внесување на податоци веројатно ќе ја поседува апликацијата што ја користи или во моментов го користи за внесување на податоци.

Погледнете ги самите корисници. Иако нивните мислења генерално ги одредуваат она што луѓето се ангажираат, но постојат значителни разлики во тоа како се користат одредени позиции. Спроведување на интервју за потенцијални корисници, можете да го додадете вашето мислење - дали името на пост ги исполнило должностите.

Погледнете ја постоечката документација. Документацијата за претходните софтверски верзии дава приближен концепт дека корисникот треба да го знае за употребата на програмата. Сепак, запомнете дека крајните корисници не се заинтересирани за тоа како функционира програмата, важно е да знаат што можат да направат со него.

Ги утврдува задачите кои се неопходни за оваа работа и кои задачи мора да се извршат пред овие задачи да се извршат.

Сликата насловена напишана софтверска документација Чекор 6

3. Определете го соодветниот формат (и) на документацијата. Софтверската документација може да биде структурирана во еден од двата формати - Референтни водич и упатства за употреба. Понекогаш е подобро да се избере мешана верзија на овие два формати.

Референтниот водич е дизајниран да ги објасни алатките на софтверот (копчиња, табели, поле и дијалогот) и како функционира овој алат. Многу брзи датотеки се напишани во овој формат, а контекстот поттикнува помош Покажи ја саканата тема откако корисникот ќе кликне на копчето "Помош" на саканиот екран.

Инструкциите за употреба објаснува како да го користите софтверот за да извршите одредена задача. Упатството за употреба често има печатен водич или PDF формат, иако некои поттикнувања вклучуваат теми за тоа како да извршат одредена задача. (Овие референтни теми обично не се контекстуални, иако тие можат да бидат хиперврски) Упатството за употреба често има форма на референтна книга со опис на задача и упатства за чекор-по-чекор.

Сликата насловена напишана софтверска документација Чекор 7

Четири. Да одлучи кој формат (формати) на документацијата треба да биде. Софтверска документација за крајните корисници може да биде еден или повеќе формати: водич за печатење, документи во PDF формат, датотеки со врвот или онлајн помош. Секој од овие формати е создаден за да му покаже на корисникот како да ја користи секоја програма - било да е краток преглед или водич. Како и во случај на брза датотеки и онлајн помош, документацијата може да има демонстрациски видео или текст со слики.

Совети и онлајн датотеки за помош мора да имаат упатства, пребарување по клучни зборови, што ќе му овозможи на корисникот брзо да ги пронајде потребните информации. Иако алатките за брзи датотеки можат автоматски да креираат упатства, подобро е да го направите ова рачно користејќи ги термините што корисниците најверојатно ќе станат пребарување.

Сликата насловена напишана софтверска документација Чекор 8

Пет. Изберете соодветна алатка за креирање документација. Упатствата за печатење или PDF формат може да бидат напишани во текстуални уредници, како што се "Word" или "FrameMaker", во зависност од должината и сложеноста на прирачникот. Советните датотеки можат да бидат напишани со користење на такви развојни алатки како "Robohelp", "помош и прирачник", "DOC-TO-HOLD", "Flare", "Helplogix" или "Helpserver".

Совети

Текстот треба да биде лесен за читање, сликите треба да бидат лоцирани колку што е можно поблиску до текстот на кој тие припаѓаат. Лизнете ја документацијата за делови и логички теми. Секој дел или тема треба да се однесува на одредено прашање, без разлика дали тоа е една програма или задача. Поврзани прашања треба да бидат наведени "за да се види и" со хиперврска, ако е потребно.
Сите алатки за креирање документација кои се наведени погоре може да се надополнат со програмата за слики од екранот, како што се Snagit, ако документацијата бара одреден број на слики од екранот. Како и со другите документи, екранот треба да објасни како функционира софтверот, а не да го заведе корисникот.
Исто така важно е тонот на документацијата за пишување, особено ако е напишана за крајните корисници. Користете го второто лице "Вие", наместо на трети лица "корисници".

Што ви треба

Алатка за пишување документација / Дебила
Алатка за создавање на слики од екранот