Riktlinjer för redigeringsformat för externa medarbetare guidelines
Den här sidan innehåller redaktionella riktlinjer för externa författare som skapar innehåll eller uppdaterar befintligt innehåll på Experience League. Innan du börjar ser du till att:
- Bekanta dig med Markering redigering
- Kontrollera stavning och grammatik i artiklar
- Använd en användarvänlig ton, enhetlig presentation och enkla meningar för att förbättra maskinöversättning
- Följ god praxis och redaktionella standarder på denna sida
Riktlinjer för format style-guidelines
Tänk på följande när du skriver dokumentation.
- Skriv kortfattat: Slösa inte bort ord. Håll meningarna korta och koncisa. Fokusera på artikeln. Minsta antal anteckningar.
- Fokusera på målgrupp och syfte: Innan du börjar skriva ska du tydligt avgöra vem kunden är och vilken uppgift han eller hon försöker utföra. Skriv en artikel som hjälper kunden att utföra uppgiften.
- Använd exempel: Ge exempel på koncept.
- Ordna ditt innehåll: Skapa avsnitt för att dela upp instruktioner i mer hanterbara grupper med steg. Använd en skärmbild när den ger klarhet.
Bästa metoder för tekniskt skrivande writing-tips
Tekniskt skrivande, särskilt för programvarudokumentation, är en specialiserad bransch. Även den mest produktiva romantiken flödar om när man skriver på teknik - inte för att materialet är komplext eller tekniskt, utan för att det inte är lätt att göra komplex, teknisk information enkel. För att lyckas måste innehållet vara strukturellt konsekvent, skannerbart, återanvändbart och flöda genom publiceringsflödet utan struktur- och syntaxfel.
I följande avsnitt beskrivs vanliga problem som nya skribenter måste bevaka:
Rubriker som inte åtskiljs med text (dubbla rubriker) double-headings
Om du har två rubriker utan text som skiljer dem åt, lägger du till text som saknas (för att infoga den andra ämnesrubriken). Du kan också ta bort en av rubrikerna. Den andra är antagligen onödig.
Till exempel: Översikt har inget syfte här:
-
Om den andra rubriken råkar vara Översikt, det är antagligen onödigt. Ditt H1-stycke och det första stycket fungerar som en konceptuell översikt över artikelns ämne.
-
För SEO-ändamål finns på liknande sätt fristående rubriker som Översikt och Introduktion är inte användbara själva. Namnge den produkt eller funktion som du presenterar. (Exempel: Översikt över utfallsrapporter)
Inkonsekventa korsreferensrubriker maps
Använd Mer information rubriker för korsreferenslistor (eller kartor). Exempel:
Vägledning för korsreferenslistor
- Använda en punktlista för korsreferenserna
- Använd kursiv stil för det formella namnet på stödlinjer eller sidnamn (när länktext inte används)
- Skiljer inte rubriken (eller någon rubrik)
- Undvik siffror i rubriker
Innehållsförteckningspost, vägbeskrivning och sidnamn matchar inte toc
Eftersom vi hanterar innehållsförteckningsfilen manuellt är dessa avvikelser enkla misstag. Kontrollera att innehållsförteckningsposten matchar sidnamnet (H1). Se även till att den överensstämmer med den synliga sökvägen.
Vägledning om innehållsförteckningar och listor
- Du kan behöva korta ned innehållsförteckningsposten, men den måste tydligt relatera till sidnamnet och sidbeskrivningen.
- Brödkrummar hämtas in från rubrikens metadata, så att de kan skilja sig åt (för SEO-syften).
Citattecken i stället för kursiv quotes
Det är svårt att motstå att lägga till citattecken runt ett ord eller en fras. Citattecknen är dock avsedda för tal och används nästan aldrig i produktdokumentationen.
Vägledning om citattecken
- Vanligtvis fungerar kursiv stil bättre än citattecken (för felmeddelanden, unika eller främmande ord osv.).
- Använd fet och UICONTROL för gränssnittselement.
Förfaranden steps
Skriva en procedur ( uppgift innehållstyp) är inte en talang som vi föds med. Att skapa en läsbar, tydlig procedur är en övning.
Vägledning för steg
- En procedur är en serie steg. Ett steg är en kort, numrerad enkel mening -kommando.
- Börja varje steg med ett verb eller Till infinitiv (för att rikta läsaren till målet, som i, Om du vill vara inloggad aktiverar du Fortsätt vara inloggad ). Om ett steg har ett specifikt mål inom den övergripande proceduren anger du målet före åtgärden.
- Om du har information om steget (en innehållstyp som kallas steginformation lägger du till det efter steget (indraget med steget) eller efter resursen (en skärmbild, video eller en lista med gränssnittsbeskrivningar).
- Om steget har två åtgärder (till exempel Välj det här, sedan det), skriva den som en enda kort mening.
- Begränsa dina arbetsmoment till cirka sju till tio steg. Om du skapar mer än tio steg i en uppgift behöver du troligen dela upp den i två uppgifter. Använd ditt bästa omdöme här.
- Använd inte rubriker som steg i produktdokumentationen. (Undantag nedan för självstudiekurser.)
- För flersidiga självstudiekurser kan du tillåta rubriker som steg. Numrera dem dock inte. I stället för att stava ut Steg 1:, Steg 2: och så vidare.
Exempelprocedur
Här följer en välstrukturerad procedur för inloggning på Adobe:
Logga in på Adobe:
- På
Adobe.com, markera Experience Cloud. - Välj Logga in.
- Välj Personligt konto.
- Om du vill vara inloggad väljer du Fortsätt vara inloggad.
- Skriv ditt namn och lösenord.
- Välj Logga in.
Parallella listor lists
Att använda parallell konstruktion för listor gör det enkelt att läsa och skanna. Listor innehåller en innehållsförteckning (innehållsförteckning), punktlistor (osorterade) eller numrerade listor.
Exempel på innehållsförteckning med parallella poster:
Ovanstående innehållsförteckning är ett bra exempel eftersom:
- Konceptuella överordnade poster är substantiv eller substantivfraser
- Rutiner (uppgifter) är aktiva verb (inte GRUND)
- Alla poster använder inledande versal i mening
Metadata för titel och beskrivning metadata
Titel och description metadata är viktiga för SEO, innehållsidentifiering och innehållskvalitetspoäng på Experience League.
Här är några exempel på titlar och beskrivningar:
Beskrivningar av konceptartiklar
- Läs om segment i Adobe Analytics. Få hjälp med att konfigurera segmenteringspanelen i en arbetsyta.
- Hitta hjälp om hur du använder segment i en sidvisningsrapport i Adobe Analytics.
Beskrivningar av procedur-/uppgiftsartiklar
- Lär dig hur du skapar ett segment i Adobe Analytics.
- Skapa ett segment i Adobe Analytics. Lär dig hur du väljer, konfigurerar och kör en rapport baserat på det segment du skapar.
Vilken du använder beror på artikelns storlek och omfattning.
Rubrik för en konceptartikel
- Segment i rapporter om sidvyer
Titel för en procedur/uppgiftsartikel
- Skapa ett segment för en sidvyrapport
(Kom ihåg att pipe och product name läggs till automatiskt i titlar.)
Olika sätt att förbättra klarheten (och Acrolinx-poäng) tips
Här finns enkla sätt att förbättra innehållsdesign, klarhet och läsbarhet. Dessa hjälper också till att förbättra Acrolinx-stilpoängen och CQI-poängen på ExL.
Svag: Campaign v8 lanseras i juni.
Stark: Campaign v8-utgåvor i juni.
Det är alltid lättare att läsa dagens spänningar för kunderna.
Mycket, extremt, otroligt…
Adverbs är extra ord som inte ger någon större betydelse om du använder tydliga och exakta verb, klausuler och adjektiv.
Exempel:
Svag: Skapa och hantera egenskaper
Stark: Skapa och hantera egenskaper
- Undvik För att (det betyder inget). Allt du behöver är till.
- Undvik Utnyttja. Det låter kanske mer tekniskt, men det är det inte. Utnyttja medel att på ett bra sätt utnyttja, särskilt något som inte var avsett för ändamålet, men som.
- Undvik semikolon: Använd en punkt i stället och börja en ny mening. Halvkolon gör det onödigt komplext.
- Kolon: Använd kolon för att presentera en lista. Använd kolon sparsamt i meningar. Inled det första ordet med versal efter ett kolon i en mening.
- Använd kommatecknet Oxford (tre kommatecken i en lista).
- Håll meningens längd under 39 ord.
- Navigering: use gå till eller navigera till.
- Undvik rå URL-text (använd användarvänlig länktext) såvida inte sökvägen visas som viktig information.
Klicka är ett enhetsspecifikt ord (med tillgänglighetsproblem) och trenden är att gå ifrån det. Här är förslag på hur du kan ändra den:
- Navigering: Gå till Arkiv > Skriv ut.
- Klicka: Välj Arkiv > Skriv ut eller Välj OK.
Se Beskriva interaktioner med användargränssnittet för fler idéer om det bästa ordet i olika situationer.
Några fler metodtips och resurser:
- Skannerbart innehåll: Hjälp läsarna att snabbt hitta det de behöver, eller att identifiera sig precis lika snabbt när de inte är där de behöver vara. Att skriva för att underlätta skanningen kan vara till hjälp.
- Nummer: I brödtexten kan du skriva ut hela tal från noll till nio och använda siffror för 10 eller högre. Se Nummer.
- Skriv som du talar, är projektvänlig och kom till saken snabbt.
Se Top 10 Writing Tips i Microsoft® Style Guide för mer information.
Alt-text alt-text
Lägg till meningsfull alt-text till dina resurser (bilder). Överväg alternativ text som matchar:
- Det mål som kunderna kan uppnå (uppgifts- eller konceptnamn)
- Funktionen eller sidan som du visar
- Ikonnamnet som du visar
Google ser alt-text i SEO-resultat.
Lokalisering - DNL och UICONTROL localization
Du behöver inte bekymra dig om din produkt är lokaliserad eller om de språk som ExL använder. Du kan dock förbättra kvaliteten på lokaliseringen genom att använda följande två (obligatoriska) taggar:
-
DNLDNL betyder inte lokalisera. Du använder det bara för varumärken som tillhör Adobe och alla måste vara på engelska.
Exempel på syntax:
Adobe CampaignellerWorkfrontDNL är inte avsett för filnamn eller URL-adresser.
-
UICONTROLUICONTROL indikerar en gränssnittskontroll (t.ex. ett alternativ, fält, flik, sida, alternativgrupp eller funktionsnamn i användargränssnittet).
Exempel på syntax:
Select **Project**, then select **Save**.
Använda Adobe i produktnamn product-names
För företagsidentitet omfattar vi vanligtvis Adobe i den första referensen till en produkt på stödlinjenivå. Beroende på utrymmet kan du släppa Adobe i en rubrik, men den första referensen i brödtexten ska då innehålla det fullständiga namnet. Vissa produkter, som Adobe Audition och Adobe Premiere Pro, kräva att Adobe används på första eller mest framträdande referensen i varje säkerhetspunkt, eftersom det är en del av det juridiska, varumärkesskyddade namnet.
Första stycket firstparas
Det första stycket ska definiera ämnet och beskriva vad läsaren lär sig av att läsa artikeln.
Exempel första stycket (begrepp):
Målgrupper är samlingar med besökare (en lista med besökar-ID:n). Adobe hanterar översättningen av besöksdata till målgruppssegmentering. Att skapa och hantera målgrupper liknar alltså att skapa och använda segment, med möjlighet att dela målgruppssegmentet till Experience Cloud.
Exempel på första stycket (uppgift):
Skapa kundattributskällan (CSV- och FIN-filer) och överför data. Du kan aktivera datakällan när du är klar. När datakällan är aktiv delar du attributdata till Analytics och Target.
SEO-tips för första stycken seo
- Inkludera söktermer i första stycken.
- Använd termer som används av läsare.
- Inkludera synonymer och vid behov tidigare användning av termer. Exempel:"Tjänsten Experience Cloud ID (ECID), som tidigare kallades besökar-ID eller som akronymer som MID, MCVID, ger ett universellt, beständigt ID som identifierar besökare."
- Inkludera SEO-termer i länkar.
- Undvik att placera viktiga termer i komplexa tabeller. Komplexa tabeller ger inte tillförlitliga sökresultat. Texten i bilderna söks inte igenom. Bildtexter söks igenom.
Versaler capitalization
- I formatet Adobe används inledande versal i mening för alla titlar, rubriker, underrubriker och sidnavigeringselement.
- Alla ord är gemener utom det första ordet och de rätta orden, till exempel namnen på varumärken, lösningar och tjänster.
- Matcha skiftläget i produktnamnen för verktyg, alternativ, menyalternativ, dialogrutor och fält.
Innehållsförteckning using-toc
The TOC.md är innehållsförteckningen. Varje guide ska ha en.
Redaktionell vägledning för innehållsförteckning
- Versaler: Använd alltid inledande versal i mening för varje post (exklusive akronymer). Ändra bara till versaler för formella produktnamn eller gränssnittselement (sidor, flikar, fält, alternativ och så vidare). Matcha gränssnittet när du refererar till det.
- Verbform och parallellitet: Använd ett ofrånkomligt verb och undvik gropar. Innehållsförteckningarna är listor, så försök alltid att hålla listor parallella oftast. Det finns undantag som ibland inte kan undvikas. Använd substantiv och substantivfraser för konceptuella sidor. Använd verb för uppgifter.
Syntaxvägledning
- En avsnittsrubrik (överordnad) i innehållsförteckningen kan inte vara en länk. den inte har någon sida med innehåll. Den bör innehålla en ankarpunkt som
{#processing-rules}. - Du måste använda rätt syntax för avsnittsrubriker i innehållsförteckningen (till exempel
+ Processing rules {#processing-rules}) och artiklar i innehållsförteckningen (till exempel+ [Article name](article.md)). - Innehållsförteckningens artikelposter kan vara en förkortad version av artikeltiteln. Följ standarderna för att skriva översikter, begrepp och uppgifter i det här dokumentet.
- Undvik att lägga till samma fil flera gånger i en innehållsförteckning (eller i flera innehållsförteckningar). Om du gör det orsakar det ett udda beteende.
- Om ditt svar innehåller flera användarhandböcker måste dina användarhandböcker finnas på samma nivå, t.ex. underkatalogerna i
helpkatalog. Varje katalog för användarhandboken måste ha en innehållsförteckningsfil. Inga kapslade användarhandböcker.
Fet och kursiv bold
- Använd endast fet text för gränssnittselement som du klickar på i en procedur (och med UICONTROL).
- Använd kursiv stil för att framhäva eller när ett ord är förvirrande utan det. Exempel: ett främmande ord, eller när du beskriver ett ord eller definierar en term.