Программалык камсыздоо документтери – бул макалалардын жыйындысы. Бирок алар деле сени жинди кылып коюшу мүмкүн. Биринчиден, сиз керектүү нускамаларды издеп көп убакыт өткөрөсүз. Ошондо сиз түшүнүксүз текстти түшүнөсүз. Жазылгандай кылып жатасыз, бирок маселе чечилген жок. Башка макала издейсиң, толкундайсың... Бир сааттан кийин баарын таштап, кетесиң. Мына ушундай начар документация иштейт. Муну эмне кылып, аны кантип оңдоо керек - кесиптин астынан окуңуз.
Биздин эски документтерибизде кемчиликтер көп болчу. Жогоруда сүрөттөлгөн сценарий биздин кардарларга таасирин тийгизбеши үчүн, биз аны дээрлик бир жылдан бери кайра иштеп жатабыз. Карачы, и .
1-маселе: түшүнүксүз, начар жазылган макалалар
Документти түшүнүү мүмкүн болбосо, анын эмне кереги бар? Бирок эч ким атайылап түшүнүксүз макалаларды жазбайт. Алар автор аудиторияны жана максатты ойлобогондо, суу куюп, текстте каталарды текшербегенде болот.
- угуучулар. Макала жазуудан мурун окурмандын даярдыгы жөнүндө ойлонуу керек. Жаңы баштагандар үчүн макалада негизги кадамдарды өткөрүп жибербеш керек жана техникалык терминдерди түшүндүрбөстөн калтырбашы керек, бирок профессионалдарга гана керек болгон сейрек кездешүүчү өзгөчөлүк жөнүндө макалада PHP сөзүнүн маанисин түшүндүрүп беришиң керек.
- максат. Дагы бир нерсени алдын ала ойлонуш керек. Автор так максат коюп, макаланын пайдалуу таасирин аныктап, аны окугандан кийин окурман эмне кылаарын чечиши керек. Эгер бул аткарылбаса, анда сиз сүрөттөмө үчүн сүрөттөмө менен аяктайсыз.
- Суу жана мүчүлүштүктөр. Көптөгөн керексиз маалыматтар жана бюрократизм, каталар жана каталар кабыл алууга тоскоол болот. Окурман грамматикалык нацист болбосо да, тексттеги этиятсыздык аны өчүрүп коюшу мүмкүн.
Жогорудагы кеңештерди карап көрүңүз, ошондо макалалар айкыныраак болуп калат - кепилденген. Аны дагы жакшыраак кылуу үчүн, биздин колдонуңуз .
Маселе 2. Макалалар бардык суроолорго жооп бербейт
Документация өнүгүүнү камсыз кылбай, реалдуу суроолорго жооп бербесе жана андагы каталар жылдар бою оңдолбосо, бул жаман. Бул көп автордун эмес, компаниянын ичиндеги процесстерди уюштуруунун көйгөйлөрү.
Документация өнүгүүгө шайкеш келбейт
Функция мурунтан эле чыгарылган, маркетинг аны жабууну пландаштырууда, андан кийин жаңы макала же котормо дагы эле документтерде жок экени белгилүү болду. Мындан улам чыгарууну да кийинкиге жылдырууга туура келди. Сиз каалагандай өз убагында техникалык жазуучуларга тапшырмаларды тапшыруу үчүн баарын сураса болот, бирок ал иштебейт. Эгерде процесс автоматташтырылбаса, кырдаал кайталанат.
YouTrack'ке өзгөртүүлөрдү киргиздик. Жаңы функция жөнүндө макала жазуу милдети техникалык жазуучуга ошол эле учурда функция сынала баштаганда түшөт. Андан кийин маркетинг илгерилетүү үчүн даярдануу үчүн бул тууралуу үйрөнөт. Эскертмелер Matermost корпоративдик мессенжерине да келет, андыктан иштеп чыгуучулардын жаңылыктарын өткөрүп жиберүү мүмкүн эмес.
Документтер колдонуучунун суроо-талаптарын чагылдырбайт
Биз минтип иштегенге көнүп калдык: бир өзгөчөлүк чыкты, ал жөнүндө сүйлөштүк. Биз аны кантип күйгүзүү, өчүрүү жана майда тууралоолорду жасоону сүрөттөп бердик. Бирок кардар биздин программаны биз күтпөгөндөй колдонсочу? Же анын биз ойлобогон каталары барбы?
Документтер мүмкүн болушунча толук болушун камсыз кылуу үчүн биз колдоо сурамдарын, тематикалык форумдардагы суроолорду жана издөө системаларындагы суроо-талаптарды талдап чыгууну сунуштайбыз. Эң популярдуу темалар техникалык жазуучуларга өткөрүлүп берилет, алар учурдагы макалаларды толуктай алышат же жаңысын жаза алышат.
Документациялоо жакшыртылбай жатат
Аны дароо кемчиликсиз аткаруу кыйын, дагы эле каталар болот. Сиз кардарлардын пикирлерине үмүттөнсөк болот, бирок алар ар бир ката, так эместик, түшүнүксүз же негизсиз макалалар жөнүндө кабарлашы күмөн. Кардарлардан тышкары, кызматкерлер документтерди окушат, демек, алар ошол эле каталарды көрүшөт. Бул колдонсо болот! Сиз жөн гана көйгөйдү билдирүү оңой боло турган шарттарды түзүшүңүз керек.
Бизде ички порталда топ бар, анда кызматкерлер документтештирүү боюнча сын-пикирлерин, сунуштарын жана идеяларын калтырышат. Колдоо үчүн макала керекпи, бирок ал жокпу? Сыноочу так эместигин байкадыбы? Өнөктөш каталар боюнча өнүгүү менеджерлерине даттандыбы? Барлыгы осы группада! Техникалык жазуучулар кээ бир нерселерди дароо оңдоп, айрымдарын YouTrack'ке өткөрүп беришет жана башкаларга ойлонууга убакыт беришет. Тема өлүп калбашы үчүн, мезгил-мезгили менен топтун бар экенин жана пикирлердин маанилүүлүгүн эскертип турабыз.
Маселе 3. Туура макаланы табуу көп убакытты талап кылат.
Табылбаган макала, табылбаган макаладан артык эмес. Жакшы документациянын урааны "Издөө оңой, табуу оңой" болушу керек. Буга кантип жетишсе болот?
Структураны уюштуруу жана темаларды тандоо принцибин аныктоо. Окурман “бул макаланы кайдан тапсам болот?” деп ойлобоосу үчүн структура мүмкүн болушунча ачык болушу керек. Жыйынтыктап айтканда, эки ыкма бар: интерфейстен жана тапшырмалардан.
- Интерфейстен. Мазмун панелдин бөлүмдөрүн кайталайт. Бул эски ISPsystem документтеринде болгон.
- Тапшырмалардан. Макалалардын жана бөлүмдөрдүн аталыштары колдонуучулардын милдеттерин чагылдырат; Титулдар дээрлик дайыма этиштерди жана "кантип" деген суроого жоопторду камтыйт. Эми ушул форматка өтүп жатабыз.
Кандай ыкманы тандабаңыз, тема колдонуучулар издеп жаткан нерсеге ылайыктуу экенин жана колдонуучунун суроосуна өзгөчө жооп бере тургандай чагылдырылганын текшериңиз.
Борборлоштурулган издөөнү орнотуңуз. Идеалдуу дүйнөдө издөө ката жазсаңыз же тилде ката кетирсеңиз да иштеши керек. Биздин Конфлуенстеги издөөбүз буга чейин бизди кубандыра албайт. Эгерде сизде көп продуктулар болсо жана документтер жалпы болсо, издөөнү колдонуучу бар бетке ылайыкташтырыңыз. Биздин учурда, башкы беттеги издөө бардык өнүмдөр үчүн иштейт, ал эми сиз белгилүү бир бөлүмдө болсоңуз, анда андагы макалалар үчүн гана.
Мазмун жана нан күкүмдөрүн кошуу. Ар бир баракта меню жана нан күкүмдөрү болгондо жакшы - колдонуучунун каалаган деңгээлге кайтуу мүмкүнчүлүгү менен учурдагы баракка жолу. Эски ISPsystem документтеринде мазмунга өтүү үчүн макаладан чыгуу керек болчу. Ыңгайсыз болгондуктан, жаңысына оңдоп койдук.
Шилтемелерди продуктуга жайгаштырыңыз. Эгерде адамдар бир эле суроо менен кайра-кайра колдоого келсе, интерфейске анын чечими менен кыйытма кошуунун мааниси бар. Колдонуучу көйгөйгө туш болгондо маалыматыңыз же түшүнүкүңүз болсо, аларды почта тизмеси менен да билдире аласыз. Аларга кам көргүлө жана колдоо жүгүн алып салгыла.
Калкыма терезенин оң жагында ISPmanager доменин башкаруу бөлүмүндө DNSSEC орнотуу жөнүндө макалага шилтеме
Документтердин ичинде кайчылаш шилтемелерди орнотуңуз. Бири-бири менен байланышкан макалалар "байланыштуу" болушу керек. Эгерде макалалар ырааттуу болсо, ар бир тексттин аягында алдыга жана артка жебелерди кошууну унутпаңыз.
Сыягы, адам алгач өзүнүн суроосуна жооп издеп сизге эмес, издөө системасына барат. Техникалык себептерден улам ал жерде документтерге шилтемелер жок болсо, бул уят. Ошентип, издөө системасын оптималдаштыруу жөнүндө кам көр.
Маселе 4. Эскирип калган макет кабылдоого тоскоол болот
Начар тексттерден тышкары, документтер дизайн менен бузулушу мүмкүн. Эл жакшы жазылган материалдарды окууга көнүп калган. Блогдор, социалдык тармактар, медиа - бардык мазмун кооз гана эмес, ошондой эле окууга оңой жана көзгө жагымдуу. Андыктан, төмөндөгү скриншоттогудай текстти көргөн адамдын азабын оңой эле түшүнө аласыз.
Бул макалада ушунчалык көп скриншоттор жана урунттуу учурлар бар, алар жардам бербейт, бирок кабылдоого гана тоскоол болот (сүрөт чыкылдатса болот)
Сиз көп эффекттер менен документациядан узак окууну жасабашыңыз керек, бирок сиз негизги эрежелерди эске алышыңыз керек.
Макет. Негизги тексттин туурасын, шрифти, өлчөмүн, аталыштарын жана толтурууну аныктаңыз. Дизайнерди жалдап, жумушту кабыл алуу же өзүңүз жасоо үчүн Артём Горбуновдун “Типография жана макет” китебин окуп чыгыңыз. Ал макеттин бир гана көрүнүшүн көрсөтөт, бирок бул жетиштүү.
Бөлүнүштөр. Текстте эмнеге басым жасоо керектигин аныктаңыз. Эреже катары, бул интерфейстеги жол, баскычтар, коду, конфигурация файлдары, "Эскертүү" блоктору. Бул элементтердин бөлүштүрүлүшү кандай болорун аныктап, аларды ченемдик укуктук актыларга жазыңыз. Канчалык аз разряд болсо, ошончолук жакшы экенин унутпаңыз. Алар көп болгондо текст ызы-чуу болот. Ал тургай, тырмакчалар өтө көп колдонулса, ызы-чуу жаратат.
скриншоттору. Кандай учурларда скриншоттор керек экенин команда менен макулдашып алыңыз. Албетте, ар бир кадамды сүрөттөөнүн кереги жок. Скриншоттордун көп саны, анын ичинде. өзүнчө баскычтар, кабылдоого тоскоол болот, макетти бузат. Өлчөмүн, ошондой эле скриншоттордогу урунтуучу жерлердин жана кол тамгалардын форматын аныктаңыз жана аларды ченемдик укуктук актыларга жазыңыз. Иллюстрациялар ар дайым жазылгандарга дал келиши жана актуалдуу болушу керек экенин унутпаңыз. Дагы, эгерде продукт дайыма жаңыланып турса, бардыгына көз салуу кыйын болот.
Тексттин узундугу. Өтө узун макалалардан алыс болуңуз. Аларды бөлүктөргө бөлүп, эгер бул мүмкүн болбосо, макаланын башына анкердик шилтемелер менен мазмунду кошуңуз. Макаланы визуалдык түрдө кыскартуунун жөнөкөй жолу - окурмандардын тар чөйрөсүнө керектүү техникалык деталдарды спойлердин астына жашыруу.
Жылдар. Макалаларыңызда бир нече форматтарды бириктириңиз: текст, видео жана сүрөттөр. Бул кабылдоону жакшыртат.
Көйгөйлөрдү кооз макет менен жабууга аракет кылбаңыз. Чынын айтсам, биз өзүбүз "ороочу" эскирген документтерди сактап калат деп үмүттөнгөнбүз - андан майнап чыккан жок. Тексттерде ушунчалык көп визуалдык ызы-чуу жана керексиз деталдар камтылгандыктан, жоболор жана жаңы дизайн күчүн жоготту.
Жогоруда айтылгандардын көбү документация үчүн колдонгон платформаңыз менен аныкталат. Мисалы, бизде Confluence бар. Мен да аны менен иштешүүгө туура келди. Кызык болсо, биздин веб-иштеп чыгуучунун окуясын окуңуз: .
Жакшырууну кайдан баштоо керек жана кантип аман калуу керек
Эгерде сиздин документтериңиз ISPсистемдикиндей чоң болсо жана эмнеден баштоону билбей жатсаңыз, эң чоң көйгөйлөрдөн баштаңыз. Кардарлар документти түшүнүшпөйт - тексттерди өркүндөтүп, ченемдик укуктук актыларды кабыл алуу, жазуучуларды окутуу. Документтер эскирген - ички процесстерге кам көр. Эң популярдуу өнүмдөр жөнүндө эң популярдуу макалалардан баштаңыз: колдоо сураңыз, сайттын аналитикасын жана издөө системаларында сурамдарды караңыз.
Дароо айталы - бул оңой болбойт. Жана бул да тез иштеши күмөн. Эгер сиз жаңыдан баштап, дароо туура иш кылбасаңыз. Биз бир нерсени так билебиз, ал убакыттын өтүшү менен жакшырат. Бирок процесс эч качан бүтпөйт :-).
Source: www.habr.com