Luo dokumentaatiosivusto

Dokumentaatiota on monenlaista eri muodoissa. Teillä saattaa jo olla joitakin resursseja tai saatatte joutua aloittamaan alusta. Käydään läpi, miten sisältöä lisätään Archbeessa.

Kun luotte uuden dokumentin, voitte alkaa lisätä sisältöä käyttämällä joko Markdown-pikakomentoja tai mitä tahansa yli 30 mukautetusta lohkosta.

Mukautetut lohkot auttavat muotoilemaan sisällön tarpeidenne mukaan. Avataksenne ne, kirjoittakaa editorissa kenoviiva / ja selatkaa vaihtoehtoja.

Lohkot on ryhmitelty kategorioihin Perus, Media, Kehittäjä, Upota, ja Sisällön uudelleenkäyttö.

Jos esimerkiksi haluatte linkittää dynaamisesti muihin dokumentteihin, kirjoittakaa @ ja dokumentin otsikko. Tämä yhdistää dokumentin tunnukseen. Jos muutatte otsikkoa tai dokumentin sijaintia, linkki osoittaa siihen aina.

Toinen esimerkki on lohkon nimen kutsuminen. Paina / ja kirjoittakaa lohkon nimi, esimerkiksi /verticalsplit, jolloin haluamanne lohko suodatetaan näkyviin.

Kolmas vaihtoehto on käyttää sulkeita, jolloin lohkon nimi - esimerkiksi (api) - lisää API-päätepistelohkon.

Vanha kunnon kopioi-liitä-kaksikko. Mutta miksi käsitellä tätä? Koska Archbeen editori tukee Markdownia, jos haluatte liittää sisältöä tässä muodossa, saatatte saada seuraavan viestin:

Jos napsautatte peruuta-painiketta, sisältöä ei renderöidä, ja jos napsautatte valintaikkunassa OK, muunname Markdownin Archbeen lohkoiksi.

Näin teillä on koodiesimerkki, joka renderöidään koodieditorilohkona Archbeessa.

Kopiointi ja liittäminen toimii hyvin, mutta jos teillä on Markdown- tai Word-tiedostoja, miksette toisi niitä Spaceen?

Ennen minkään sisällön tuontia varmista, että napsautatte sitä Spacea, johon haluatte tuoda tiedostot. Napsautatte vain tiedostotyyppiä ja säästätte minuutteja kopiointi-liittämiseltä muista lähteistä.

API-dokumentaation laatimiseen on useita vaihtoehtoja.

Sanotaan, että käytätte OpenAPI-standardia (aiemmin Swagger). Tämä mahdollistaa tiedostojen helpon tuonnin ja synkronoinnin.

Kun sisältö on tuotu Archbeehen, se renderöidään 3-sarakkeiseen asetteluun, joka mahdollistaa helposti hallittavan dokumentaation.

Dokumentaatio saatetaan kirjoittaa GitHub-repositorioon, ja voitte jatkaa kirjoittamista GitHubissa sekä synkronoida repositorion Archbee Spacen kanssa. Hyötynä on, että voitte julkaista kyseisen Spacen mukautetussa verkkotunnuksessanne ja lisätä muita Spaceja lisätiedoille, kuten API-viitteille.

Ennen kuin aloitatte sisällön kanssa, tehkää pieni vaihe, joka vaikuttaa myöhemmin. Määrittäkää aliverkkotunnuksenne niin, että sillä on pääsy esikatselu- ja tuotantoympäristöihin. Siirtykää dokumentaatiosivulle ja noudattakaa ohjeita mukautetun verkkotunnuksen lisäämiseksi.

Useita vaihtoehtoja on saatavilla Yleinen-välilehdellä - voitte poistaa käytöstä asetuksen Hakukoneiden indeksoitavissa (jos julkinen) samasta Space Settings -näkymästä. Usein haluatte pitää tämän aktivoituna, jotta käyttäjät löytävät sivustonne hakukoneiden tulossivulta. Voitte siirtyä Public access control -vaihtoehtoon ja valita minkä tahansa viidestä vaihtoehdosta paremman hallinnan saamiseksi.

Ennen kuin kirjoitatte dokumentaatiota, miettikää tärkeimmät aiheet, jotka käsittelette. Tällä kertaa kynä ja paperi voivat auttaa teitä hahmottelemaan rakenteen.

Seuraavaksi luokaa dokumentti, muuttakaa se kategoriaksi ja antakaa sille nimi.

Kun nämä ovat valmiina, voitte lisätä dokumentteja jokaisen kategorian alle.

Aloittakaa dokumentilla, joka esittelee tärkeimmät asiat, joita käyttäjä löytää dokumentaatiosivustolta. Sen ei tarvitse olla monimutkainen; näin me teimme sen Käyttäjä- ja kehittäjäopas:ssa

Kun alatte lisätä sisältöä, työnkulun käyttö on olennaista. Tässä on yksi mahdollinen vaihtoehto, mutta voitte haluta mukauttaa sitä:

Mallien käyttäminen helpottaa sisällöntuottajien työn aloittamista. Voitte tallentaa joukon malleja auttamaan sisällöntuotannon käynnistämisessä. Jos tarvitsette inspiraatiota, uuden dokumentin luomisen yhteydessä näette sivun alareunassa painikkeen nimeltä: Start with a template. Rakentaaksenne omia mallipohjianne siirtykää vasemman reunan navigaatioon kohtaan Templates ja alkakaa luoda dokumentteja rakenteella, jota dokumenttinne tarvitsevat.

Voitte myös esitellä mukautetut lohkot, joita kirjoittaja käyttää, tai lisätä esimerkkejä muista lähteistä.

Nämä asetukset ovat dokumenttikohtaisia. Teidän täytyy siis napsauttaa oikean yläkulman kolmea pistettä ⋮ ja valita SEO-metatietojen hallinta.

Lisätkää asiaankuuluva otsikko, muuttakaa URL, kirjoittakaa metakuvaus tai ladatkaa kuva esikatseluita varten.

Välilehdellä Ulkoasu löydät brändäysvaihtoehdot, kuten Korostusväri, Logo ja Favicon, sekä muita mallipohjan vaihtoehtoja.

Tuotteiden tai palveluiden tyypistä riippuen saatat haluta käyttää eri Space URL -polkuja.

Voit käyttää yhtä Spacea ensisijaisena dokumentaationa ja luoda eri Spaces-määrityksiä muille tuotteille tai jopa niiden versioille.

Siihen on oikotie! Voit luoda kloonin mistä tahansa Spacesta, jos muutokset ovat inkrementaalisia. Tämä auttaa säilyttämään rakenteen ja tekemään muokkaukset uutta versiota varten.

Jos siis versionhallinta ja monituotetuki ovat tarpeitasi, käytä eri Spaces-määrityksiä ja lisää niihin asiaankuuluva polku tai mukautettu verkkotunnus.

Siirry kohtaan Space-linkit ja aloita navigoinnin rakentaminen.

Kotisivun päätavoitteena on auttaa kävijää siirtymään seuraavalle sivulle.

Dokumentaatiosivustosi aloitussivun rakentamisen ei tarvitse noudattaa samoja käytäntöjä kuin esittelysivuston.

Ensimmäinen dokumenttisivu on tärkeä tuotteesi tai palvelusi esittelemiseksi käyttäjille, joten sen pitäminen lyhyenä ja odotusten asettaminen auttaa pitkälle.

Voit käyttää mukautettu aloitussivu -ominaisuutta ja lisätä omaa HTML-koodiasi saadaksesi enemmän hallintaa ensimmäiseen sivuun. Inspiraatiota varten on monia vaihtoehtoja, ja jos haluat muuttaa ensimmäisen sivun ulkoasua ja tuntumaa, tämä on oikea vaihtoehto.

Tässä on esimerkki siitä, miten yksi asiakkaistamme rakensi aloitussivunsa ohjesivua varten.

Käytä mukautettu CSS-toimintoa, jos haluat lisätä oman tyylisi dokumentaatiosivustolle. Jos tunnet CSS-luokat, löydät muutamia lähtökohtia ja voit kohdistaa niitä.