LegközelebbKövetkező útmutató
Hogyan győzd le az írói blokkot mesterséges intelligencia segítségével
Alkalmazások
Alkalmazási ÚTMUTATÓ
Az AI a műszaki írók számára azt jelenti, hogy nyelvi modelleket használnak a specifikációkból és kódokból származó dokumentáció elkészítéséhez, a stílus konzisztenciájának megőrzéséhez és a docs-as-code munkafolyamatok támogatásához, miközben az író továbbra is felelős a pontosságért és a szerkezetért.
Hallgassa meg ezt az útmutatótAI-narrált · ~3 min
Ez azért fontos, mert a dokumentáció gyakran elmarad a gyorsan mozgó termékektől. Az AI felgyorsíthatja a rajzolást és a frissítéseket, de olyan paramétereket vagy viselkedést is kitalálhat, amelyek meggyőzően hangzanak.
Technical writing has been partly automated for a long time. Reference documentation is routinely generated from code comments or API specifications with tools such as Swagger UI, Redoc and Sphinx autodoc. A generatív mesterséges intelligencia próza: fogalmi magyarázatok, oktatóanyagok, példák, kiadási megjegyzések és a termékkövetelmények dokumentumaiból vagy mérnöki megjegyzésekből írt első vázlatok. Sok csapat a dokumentumok kódként modellben dolgozik. A dokumentáció Markdown vagy reStructuredText néven él a Gitben, a változások lekéréses kéréseken keresztül mennek keresztül, és a folyamatos integráció építi fel a webhelyet egy statikus helygenerátorral, mint például a Docusaurus, az MkDocs vagy a Sphinx. Ez a beállítás jól illeszkedik az AI-hoz. Drafts arrive as reviewable changes, automated checks run on every commit, and doc updates can be tied to the code changes that caused them. For style consistency, deterministic tools and AI complement each other. Az olyan linter, mint a Vale, egy stílus útmutatóból, például a Google fejlesztői dokumentációs stílus útmutatójából vagy a Microsoft írási stílus útmutatójából származó szabályokat kényszerít ki, és minden alkalommal ugyanazt az eredményt adja. AI is better at suggesting clearer phrasing, but it is less predictable. A fő kockázat a magabiztos pontatlanság. A model can invent an endpoint, a default value or a command-line flag that looks plausible. It can also describe how a product behaved in its training data rather than how it behaves now. Every generated code sample and parameter needs checking against the real system. A common misconception is that AI makes technical writers unnecessary. A munka legnehezebb része az, hogy tudjuk, mi igaz, eldöntsük, mire van szükségük a felhasználóknak, valamint az információk rendszerezése, hogy megtalálják. Az olyan keretrendszerek, mint a Diátaxis, amely szétválasztja az oktatóanyagokat, útmutatókat, hivatkozásokat és magyarázatokat, ezt a szerkezeti munkát tükrözik. A szerepek az információs architektúra, az ellenőrzés, a tartalomstratégia és az AI-olvasók írása felé tolódnak el. A 2024-es llms.txt javaslat például egy olyan fájlt javasol, amely a nyelvi modelleket a webhely legfontosabb dokumentációjához irányítja.
Az író megadja a mesterséges intelligencia OpenAPI-specifikációját és a csapat oldalsablonját, és koncepcionális áttekintést és a kezdő lépések áttekintését kéri. Ezután minden kódmintát futtatnak egy tesztkörnyezetben.
Egy dokumentumtár a Vale prose lintert futtatja folyamatos integrációban a tiltott kifejezések és a passzív hang megjelölésére. Egy mesterséges intelligencia asszisztens javasolja a megjelölt mondatok átírását, és az író mindegyiket elfogadja vagy elutasítja.
Amikor egy mérnök lekérési kérelme átnevez egy konfigurációs jelzőt, egy mesterséges intelligencia lépés elkészíti a megfelelő dokumentáció módosítását. Az író áttekinti az összevonás előtt.
Az író átstrukturálja a hosszú hibaelhárítási oldalt önálló részekre, leíró fejlécekkel. Ez segít az emberi olvasóknak és a mesterséges intelligencia asszisztenseinek, akik részleteket húznak ki a dokumentumokból.
Valószínűleg a dokumentációt folyamatosan generálják és frissítik, a kódmódosítások mellett, az AI tervezetével és az emberek jóváhagyásával. Több olvasó jut el a dokumentumokhoz az AI-asszisztenseken keresztül a böngészés helyett, ami növeli a pontos, jól strukturált tartalom értékét, amely darabokban olvasva is működik. Az olyan egyezmények, mint az llms.txt, még mindig javaslatok, elfogadásuk pedig bizonytalan. Csökkenhet a puszta tervezés iránti igény, míg a műszaki pontosságot, a tervezési információs architektúrát és a saját dokumentáció minőségét ellenőrizni tudó emberek iránti kereslet állandósult vagy nőhet. Egyelőre nem világos, hogy a munkaerőpiac hogyan fog kettészakadni.
Ingyenes hírlevél
Minden hétköznap reggel három ellenőrzött AI történet, egyszerű angol nyelven. Örökké ingyen, hirdetések nélkül.
Minden hétköznap egy e-mail. Egy kattintással lemondhat. Soha nem értékesítjük vagy osztjuk meg az Ön címét.
Teszteld magad
Azonnali visszajelzés minden válaszra, és megosztható tanúsítvány egy ellenőrizhető azonosítóval, miután sikeresen teljesít egy kurzust.
Támogassa az ingyenes AI oktatást. AI Understanding egy 501(c)(3) nonprofit – nincs hirdetés, nincs fizetőfal, soha. Tegyen adományt
Az AI a műszaki írók számára azt jelenti, hogy nyelvi modelleket használnak a specifikációkból és kódokból származó dokumentáció elkészítéséhez, a stílus konzisztenciájának megőrzéséhez és a docs-as-code munkafolyamatok támogatásához, miközben az író továbbra is felelős a pontosságért és a szerkezetért. It matters because documentation often falls behind fast-moving products. AI can speed up drafting and updates, but it can also invent parameters or behavior that sound convincing.
A Vale egy prózai linter, amely determinisztikusan érvényesíti a stílusszabályokat. Az egyértelműbb megfogalmazásra vonatkozó AI-javaslatok kevésbé kiszámíthatók.
A docs-as-code esetén a dokumentumok a Gitben Markdown vagy hasonló néven élnek, lekéréseken mennek keresztül, és a CI statikus helygenerátorokkal készíti őket.
A Diátaxis a dokumentációt oktatóanyagokra, használati útmutatókra, hivatkozásokra és magyarázatokra osztja, amelyek mindegyike más-más felhasználói igényt szolgál ki.
A magabiztos pontatlanság a fő kockázat. A végrehajtható minták meghiúsítanak egy kitalált paramétert a buildben.
Proposed in 2024, llms.txt is a convention for guiding language models to important docs. Elfogadása még bizonytalan.
Tanulj tovább
További útmutatók készültek ehhez a témához
LegközelebbKövetkező útmutató
Hogyan győzd le az írói blokkot mesterséges intelligencia segítségével
Alkalmazások