Alkalmazási ÚTMUTATÓ

AI műszaki íróknak

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

Ezen az oldalon4 perc olvasás
  1. Áttekintés
  2. Mély merülés
  3. Valós megvalósítás
  4. Az AI jövője műszaki íróknak
  5. A gyakorlatba ültetés
  6. Folytassa a felfedezést
  7. Gyakran ismételt kérdések

Áttekintés

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.

Mély merülés

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.

Valós megvalósítás

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.

Az AI jövője műszaki íróknak

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.

A gyakorlatba ültetés

Miért számít

  • Építési lehetőségek. Az alkalmazásszintű tervezés határozza meg, hogy az AI javítja-e a valós eredményeket.
  • Csapat és munkafolyamat. A jó munkafolyamat-integráció olyan termelékenységnövekedést eredményez, amelyben a felhasználók megbízhatnak.
  • Kockázat és biztonság. A jól körülhatárolt felhasználási esetek csökkentik a változtatások fáradtságát és a végrehajtás kockázatát.

Vigyázz

  • Egy megszakadt folyamat automatizálása felerősítheti a meglévő problémákat.
  • A csapatok túlautomatizálhatják és eltávolíthatják a szükséges emberi ítélőképességet.
  • A minőség sodródhat, ha a kimeneteket nem értékelik folyamatosan.

Következő lépések

  1. Térképezze fel az aktuális munkafolyamatot, és határozza meg a legnagyobb súrlódású lépést.
  2. Emberi ellenőrzőpontok meghatározása a teljes automatizálás előtt.
  3. Tanítsa meg a felhasználókat az utasításokról, az eszkalációs utakról és a minőségi szabványokról.
  4. Kövesse nyomon a feladat szintű eredményeket a tartós érték megerősítéséhez.

Folytassa a felfedezést

Ingyenes hírlevél

Szerezze meg a napi AI összefoglalót

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

Take the AI for Technical Writers quiz

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.

Kezdő kvíz

Támogassa az ingyenes AI oktatást. AI Understanding egy 501(c)(3) nonprofit – nincs hirdetés, nincs fizetőfal, soha. Tegyen adományt

Gyakran ismételt kérdések

Mi az az AI technikai íróknak?

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.

Mit csinál a Vale-linter a docs-as-code munkafolyamatban?

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.

Mi írja le legjobban a docs-as-code-ot?

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.

Melyik négy tartalomtípust választja el a Diátaxis keretrendszer?

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.

Miért kell az AI által generált kódmintákat tesztként futtatni?

A magabiztos pontatlanság a fő kockázat. A végrehajtható minták meghiúsítanak egy kitalált paramétert a buildben.

Mi az llms.txt javaslat?

Proposed in 2024, llms.txt is a convention for guiding language models to important docs. Elfogadása még bizonytalan.