Документација је суштински део циклуса развоја софтвера. Објашњава како се користи софтвер и може укључивати корисничке водиче, АПИ референце, упутства за инсталацију и белешке о издању.
Аутоматизација ваше документације је најновији тренд јер може помоћи у уштеди времена, смањењу грешака и осигуравању доследности. Одржавање ваше документације ажурном и доступном свим заинтересованим странама олакшава сарадњу и континуирано побољшање.
Документи као код је приступ аутоматизацији документације који третира техничку документацију као код.
Шта су документи као код?
Документи као код је филозофија развоја софтвера која техничку документацију посматра као облик кода. То сугерише да треба да третирате документацију са истом ригорозношћу и процесом као софтверски код.
Идеја иза докумената као кода је да се документација третира као првокласни артефакт процеса развоја, интегришући је са животним циклусом софтвера. То значи да се документација третира као саставни део кодне базе. То значи да на њега примените исту контролу верзија, континуирану интеграцију и процесе тестирања које радите на самом коду.
У типичним документима као подешавање кода, пишете документацију у обичне текстуалне датотеке, обично у лагани језик за означавање као што је Маркдовн, ХТМЛ или реСтруцтуредТект. Затим га складиштите у истом спремишту као и изворни код. Ово олакшава управљање и праћење промена у софтверу и документацији. Такође помаже да се осигура да је документација ажурирана са најновијом верзијом кода.
Зашто би требало да користите документе као код
Пре него што су документи били код, документација се често третирала као одвојена од кода, креирана помоћу различитих алата и процеса. Овај лабавији приступ често је доводио до застареле документације и недоследности са кодом. Можете искористити неколико предности усвајањем докумената као кодног приступа.
Унапређена сарадња
Документи као код омогућавају сарадњу између програмера, техничких писаца и других заинтересованих страна у процесу развоја. Пошто се у спремишту кода налази документација, различитим странама је лако да допринесу и направе промене. Ово помаже да се осигура да је документација тачна, ажурна и свеобухватна.
Заједнички приступ документацији помаже да се осигура да она укључује све релевантне информације и да тачно одражава софтверски систем како га тумаче све стране.
Аутоматизација процеса и приступачност
Још једна предност докумената као кода је та што омогућава аутоматизованим алатима за генерисање и објављивање документације. Систем израде може аутоматски да генерише ХТМЛ или ПДФ верзије документације из обичних текстуалних датотека за објављивање на веб локацији или интерном документационом порталу. Ово чини документацију доступном већем броју заинтересованих страна.
Аутоматизацијом процеса генерисања и објављивања документације, документи као код помажу у смањењу времена и труда потребних за одржавање и објављивање документације. Омогућава развојним тимовима да се фокусирају на побољшање софтвера.
Контрола верзија
Чување документације у истом репозиторијуму кода као и софтвер олакшава управљање и праћење промена у оба.
Можете користити системи контроле верзија као што је Гит за праћење промена документације и враћање на претходне верзије ако је потребно. Ово помаже да се осигура да је документација тачна и ажурна, као и да можете пратити и ревидирати промене.
Типични документи као ток рада кода
Типични документи као ток рада кода обухватају писање, контролу верзија, прављење и хостовање:
Процес писања
Процес писања је прва фаза типичног тока рада кода докумената. Већина техничких писаца а инжењери документације користе једноставне МаркДовн, АсцииДоц или ХТМЛ. Они пишу документацију користећи алате као што су ГитБоок и Редоцли који обезбеђују несметан процес.
Контрола верзија за документацију
Документација се развија како се код развија. Биће вам потребан софистицирани систем контроле верзија као што је Гит, Пластиц СЦМ или Субверсион да бисте пратили промене у документацији ради лакше сарадње и праћења верзија.
Процес израде документације
Процес изградње укључује обраду и састављање документације у формате за испоруку. То могу бити ХТМЛ, ПДФ, ЕПУБ или други. Процес документације се обично олакшава коришћењем статичких генератора сајтова као што су Хуго и Јекилл.
Хостовање и дистрибуција документације
Процес хостовања или дистрибуције је обично последњи корак докумената као процеса кодирања. Овај процес обезбеђује да се документација достави крајњем кориснику и доступна свим заинтересованим странама. Можете користити ГитХуб или ГитЛаб странице или прилагођени портал за дистрибуцију ваше документације на вебу.
Можете да аутоматизујете Го и Јава документацију користећи ГоДоц и ЈаваДоц
Документи као филозофија кода револуционишу писање техничке документације и управљање.
Многи програмски језици, укључујући Го и Јава, пружају алате за аутоматизацију документације помоћу коментара кода. Го обезбеђује Годоц алатку, а Јава ЈаваДоц.
