Документация к софту — это просто набор статей. Но даже они могут вывести из себя. Сначала долго ищешь нужную инструкцию. Потом разбираешься в малопонятном тексте. Делаешь как написано, а проблема не решается. Ищешь другую статью, нервничаешь… Через час плюёшь на всё и уходишь. Так работает плохая документация. Что делает её такой, и как это исправить — читайте под катом.
In nostris veteribus documentis multa fuerunt vitia. Eam per annum fere iam relaboravimus ut missiones supra scriptae nostros clientes non afficiant. ecce, и .
Problema I Obscurum, male scriptum articulorum
Si impossibile est documentum intelligere, quid est illud? Sed nullus de industria scribit incomprehensibiles articulos. Eveniunt cum auctor de auditorio et proposito non cogitat, aquam infundit et textum errorum non inhibet.
- auditorium. Priusquam scripserim articulum, debes cogitare de gradu praeparationis lectoris. Consentaneum est quod in articulo incipientis non debes primas gradus omittere et technicas vocabula sine explicatione relinquere, sed in articulo perrara notam, quae solum professionales egent, significationem verbi PHP explanare debes.
- propositum. Unum aliquid cogitare in antecessum. Auctor metam luculentam apponere debet, utiliter effectum articulum determinet, et quid lector facturus sit perlectis. Si hoc non fit, descriptionis causa describendi finem habebis.
- Aqua et bugs. Multum est informationes supervacuas et officiale, errores et typos perceptioni impedit. Etsi lector grammaticae nazi non sit, neglegentia in textu eum deflectere potest.
Учтите советы выше, и статьи станут понятнее — гарантировано. Чтобы сделать ещё лучше, возьмите на вооружение наши .
Quaestio 2. Articuli non omnes quaestiones respondere
Malum est cum documenta progressionem non sustinent, quaestiones reales non respondet, et errores in ea annis non corriguntur. Hae problemata non tantum auctoris sunt, sed processus in comitatu regiminis.
Documenta non ut cum evolutionis
Pluma in remissione iam est, consilia ad eam operiendam, et tunc evenit ut novus articulus vel translatio in documentis adhuc non sit. Concedimus etiam ob hoc dilationem dimittere. Interrogare quemlibet potes ut scriptoribus technicis negotia tradere quantum vis temporis, sed non operatur. Si processus non automated, res ipsa repetet.
Mutationes YouTrack fecerimus. Negotium scribendi articulum de novo pluma cadit ad scriptorem technicum eodem momento, quo probare incipit pluma. Inde ipsum discit ut ad promotionem praeparet. Notificaciones etiam ad nuntium corporatum Mattem perveniunt, unde simpliciter impossibile est nuntios ab e tincidunt falli.
Documenta non reflectunt user petitiones
Facientes sumus sicut hoc: exivit pluma, de eo locuti sumus. Descripsimus vertere, vertere, et servando facere subtiliter. Sed quid si clientulus utitur programmate nostro aliquo modo non exspectavimus? An errores habet quos non cogitamus?
Ut documenta quam maxime completa sint, commendamus petitiones subsidiariae, quaestiones de foro thematico, et inquisitiones in inquisitionibus machinationibus. Argumenta maxime popularia ad technicas scriptores transferentur ut articulos exstantes supplere possint vel novas scribere.
Документация не совершенствуется
Difficile est recte facere, errata adhuc erunt. Exspectare potes feedback ex clientibus, sed veri simile est quod omne typo, inaccuratum, incomprehensibile vel incomprehensibile articulum referent. Praeter clientes, operarii documenta legunt, quo modo eosdem errores vident. Hoc adhiberi potest! Vos iustus postulo condiciones creandi quibus facile erit problema referre.
Coetum habemus in porta interna ubi operarii commenta, suggestiones et notiones de documentis relinquunt. Auxilio eget articulo, sed non est? Probator notavit indiligentiam? Num particeps de erroribus progressui actoribus conquestus est? Omnes in hoc coetu! Scriptores technici quaedam statim figunt, quaedam ad YouTrack transferunt, et nonnulla ad cogitandum deducunt. Ne locus ille pereat, subinde te admonemus de exsistentia coetus ac momenti feedback.
Problema 3. Longum est invenire articulum rectum.
Articulus, qui inveniri non potest, melior est quam articulus qui inveniri non potest. Sententia documentorum bonorum debet esse "facilis ad investigandum, facile ad inveniendum." Quomodo hoc assequendum?
Organizare structuram ac principium determinare argumenta eligendi. Structuram quam maxime perspicuam esse debet ut lector non cogitet: "Ubi hoc articulum invenire possum?" Summatim duplex est aditus: ab instrumento et ab operibus.
- Ab instrumento. Contentum sectiones tabellae duplicat. Hoc casu in antiquis documentis ISPsystem.
- Ab operibus. Tituli capitulorum et sectionum opera utentium reddunt; Cognomina fere semper verba continent et responsa ad quaestionem "quomodo". Nunc ad hanc formam movemur.
Quicquid adire libet, fac locus ad id quod usores quaerunt et tegitur modo quod nominatim quaestionem usoris alloquitur.
Наладить централизованный поиск. In mundo ideali, quaerere etiam cum fallunt vel errare cum lingua facere debet. Investigatio nostra in Confluentia tantum hoc nobis placere non potest. Si plures fructus habes et documentum generale est, inquisitionem sutor ad paginam in usuario est. In casu nostro, quaesitio in pagina praecipua pro omnibus productis operatur, et si iam in sectione specifica, tunc solum ad articulos in ea.
Addere contentus et medulla panis. Bonum est cum unaquaeque pagina menu medullam et medullam habet - iter usoris ad hodiernam paginam cum facultate quoquo gradu redeundi. In antiquis documentis ISPsystem, articulum exire habuisti ut ad contentum. Incommodum erat, ita in novo figebamus.
Place nexus in producto. Si homines etiam atque etiam cum eadem quaestione fulciuntur, sensum praebet cum solutione interfaciendi addere. Si notitias vel prudentias habes cum utens quaestionem experitur, eas etiam cum indice electronicarum notificare potes. Sollicitudinem ostende, et sustenta onus tolle.
In dextra in fenestra pop-upi nexus cum articulo ad DNSSEC erectionem in sectione administrationis domain ISPmanager
Eriges crucem-references in documentis. Articuli, qui inter se coniunguntur, «coniuncti sunt». Si articuli sequentiales sunt, certo sagittas ante et retro in fine cuiusque textus apponere.
Verisimile est, quis non ad te, sed ad tormentum quaerendum, responsum quaesierit. Turpe est si nullae sunt nexus cum documentis ibi technicis rationibus. Cura igitur optimization inquisitionis engine.
Quaestio 4. Outdated layout intermiscetur sensus
Praeter malos textus, documenta consilio corrumpi possunt. Homines bene scriptas materias legere solent. Diaria, retia socialia, media - omnia contenta non solum pulchra, sed etiam facilia lectu et oculis placent. Unde facile intelligis dolorem eius qui textum in tortor in infra.
Tot sunt eenshotsscrae et elucidae in hoc articulo quod non adiuvant, sed solum perceptionem impediunt (imago est clickable)
Longum documentum cum fasciculo effectuum non debes facere, sed regulas fundamentales considerare debes.
Layout. Determinare corpus textus latitudinem, fontium, amplitudinem, titulos et Nullam. Conduce excogitatorem et laborem accipias vel ipsum fac, lege Artyom Gorbunov librum "Typographia et Layout." Unam tantum sententiam sistit in extensione, sed satis satis est.
legio. Decernite quid emphasin in textu requirit. Typice haec via est in interfaciei, globulis, codice insertis, configurationis fasciculorum, "Quaeso note" caudices. Decernite quid prouincia horum elementorum futura sint ac notent normas. Meminerint minus missionem, meliorem. Cum multae sint earum, textus strepit. Etiam scntentia notas sonum creant si saepius adhibeantur.
eenshotsscray. Conveniunt cum theam in quibus casibus screenshots opus sunt. Omnibus gradibus illustrare non est certissimum opus. Magnum numerum screenshots, incl. globuli separati, perceptionem impediunt, attentum spoliant. Magnitudinem determinare necnon formas elucidationum et subscriptionum in eenshotsscray et eas in normis notare. Mementote illustrationes semper debere iis quae scriptae sunt respondere ac pertinere. Iterum, si regulariter renovatur productum, difficile erit omnium vestigia retinere.
Textus longitudo. Vitare articulos nimis longos. Partes eas divide, et si id fieri non potest, ancoras nexus ad initium articuli adde contentus. Simplex via ut articulum visibiliter breviorem efficiat, est occultare singula technica, quae exiguo circulo legentium sub vastatore sunt occultanda.
formats. Plures formas compone in articulis tuis: textum, video et imagines. Hoc perceptio melior erit.
Noli quaerere quaestiones pulchris operire layout. Honeste ipsi speravimus "involucrum" documentum iam pridem salvum fore - non elaboravit. Textus tam strepitus visualium ac singularium supervacaneorum continebat ut ordinationes ac nova consilia invalida essent.
Multa de praedictis per tribunal uteris ad documenta determinanda. Exemplum habemus Confluentes. Mihi etiam cum illo tinker. Si interest, fabulam nostram interretialem lege: .
Ubi incipere emendare et quomodo superesse
Si documenta tua tam magna est quam ISPsystem' et ubi incipias nescis, maximis quaestionibus incipe. Clientes documentum non intelligunt - textum emendare, ordinationes facere, scriptores instituendi. Documenta antiqua sunt - cura processuum internorum. Committitur cum maxime popularibus articulis de productis popularibus: subsidium roga, vide situm analytica et quaerenda in machinationibus quaerendis.
Dicamus ilicet - non erit facile. Et probabile est vel celeriter laborare. Nisi justo proficisceris, et rem iure. Unum certo scimus quod melius tempore erit. Sed processus nunquam finietur :-).
Source: www.habr.com