Automation Kit for Power Platform

Retningslinjer for oprettelse

I de følgende afsnit beskrives retningslinjer og noter til oprettelse af startdokumentation.

Retningslinjer

I de følgende afsnit beskrives tekniske, designmæssige og resultatbaserede retningslinjer for oprettelse af bidrag

Mål

Når vi bygger vores dokumentation, er det vigtigt at overveje, hvordan vi gør det muligt for vores læsere at Fald i succesens hul.

Brad Abrams definerede Succesen i 2003 som

The Pit of Success: i skarp kontrast til et topmøde, en top eller en rejse gennem en ørken for at finde sejr gennem mange prøvelser og overraskelser, vi ønsker, at vores kunder simpelthen skal falde i vindende praksis ved at bruge vores platform og frameworks. I det omfang vi gør det let at komme i problemer, fejler vi.

I betragtning af dette mål overveje følgende:

  • Giv en “ingen klippeoplevelse”

    • Hjælp administratorer og centrale styringsteams med at oprette en selvbetjeningsmodel til brug af Automatiseringssæt til Power Platform

    • Tillad brugere at gøre brug af udviklingsmiljøer til at få fat i, hvis et centralt miljø ikke er tilgængeligt, og de vil have funktioner før en test- eller produktionsinstallation af Automatiseringssæt til Power Platform

    • Diskuter brugen af prøvemiljøer med nem opsætning for at få fat i Automatiseringssæt til Power Platform

  • Giv en kanal til feedback. Giv kunderne mulighed for at komme med input til, hvad vi kan forbedre

Kontrol af kilder

  • Du har gennemført Dokumentation trin til at downloade og skubbe ændringer til GitHub-lageret
  • Nye ændringer skubbes til en ny gren og har en pullanmodning om at gennemgå ændringer
  • Al dokumentation skal enten være markdown, JSon eller statiske aktiver, der kan versionskontrolleres og gennemgås ved hjælp af standard pull-anmodningsproces

Retningslinjer for design

Hjemmeside

  • Har klar titel og undertekst, der skitserer formålet med startoplevelsen
  • Giv en opfordring til handling for at inkludere andre relaterede begivenheder. Tilmeld dig f.eks. kontortid.
  • Link til Introduktion som den primære handling for at hjælpe nye brugere med at onboarde
  • Sekundær handling for at deltage i kontortid for at hjælpe med at opbygge et fællesskab af brugere
  • Medtag felter med almindelige handlinger
  • Oversigtsliste over funktioner, der hjælper brugerne med at administrere hyperautomatiseringsprojekter
  • Sidefodsnavigation til almindelige links.

Læs Konfiguration af websted for mere information om konfiguration af startsiden.

Genbrug

  • Brug hugo-layout til at kunne angive nyt tema eller tilsidesætte det aktuelle tema ved at placere indhold i mappen site\layouts

  • Ændring af layout skal gøre det muligt at inkludere statisk HTML på mange hostingplaceringer. For eksempel

    • GitHub-sider
    • Power-sider
    • Del point
    • Statiske Azure-websteder

  • Tilgangen kan bruges som skabeloner af partnere eller kunder til at opbygge “dokumentationspakker” for at fremskynde plejefasen af Automatiseringssæt til Power Platform dokumentation

  • Giv mulighed for flere brugere af dokumentationen (f.eks. kunde- og partnercenterteams)

  • Tillad, at brugerleveret indhold medtages

  • Tillad opgraderingsproces, der gør det muligt at hente nye ændringer fra Automatiseringssæt til Power Platform Dokumentation til start

Markdown sider

  • Du kan bruge Visual Studio-kode Sådan redigeres markdown-filerne

  • Markdown-filer skal være placeret i mappen /site/content

  • Hver markdown-fil skal indeholde fælles header på hver side

title: Sample page
description: Automation Kit sample page
sidebar: false
sidebarlogo: fresh-white
include_footer: true
  • Markdown-filer skal bruge kortkoder til at integrere ethvert JavaScript

kortkoder

Korte koder giver mulighed for at inkludere dynamisk indhold på en markdown-side. Du kan læse mere om kortkoder fra Hugo kortkode dokumentation

Dette projekt indeholder også yderligere kortkoder

Indholdsfortegnelse

Tilføj Indholdsfortegnelsen følgende kortkode til din markdown for at inkludere en indholdsfortegnelse med markdown-overskrifter på siden omgivet af {{ og }}

<toc/>

Spørgsmål

Medtag et sæt spørgsmål på din side omgivet af {{ og }}

<questions name="/content/en-us/foo.json" completed="Thank you for completing foo" showNavigationButtons=false />

Parametre:

  • Navn Navnet på den JSon-fil, der indeholder spørgsmål, der skal importeres. Læse Spørgsmål For mere information om spørgsmålsfilformat
  • Afsluttet Den tekst, der skal vises, når spørgsmålene er afsluttet
  • showNavigationButtons true/falsk værdi til sko Næste/Tilbage/Fuldført navigationsknapper

Eksternt billede

Medtag et billede i størrelse fra en ekstern kilde på din side omgivet af {{ og }}

<externalImage src="https://github.githubassets.com/images/icons/emoji/unicode/1f6a7.png" size="16x16" text="Construction Icon"/>

Parametre:

  • Src Kildestien til det billede, der skal importeres
  • størrelse Størrelsen i pixels for at ændre størrelsen på kildebilledet til
  • Tekst Den alternative tekst, der skal medtages i billedet

Noter

Opsætning af GitHub-sider

Følgende trin blev brugt til at konfigurere GitHub-siderne for webstedet

  1. Tjek dokumentationsgren

    git checkout gh-pages

  2. Hugo extended er installeret

    • Du kan også installere med chokolade på vinduer
    choco install hugo-extended -confirm

  3. Skift til webstedsmappe

    cd site

  4. Test dine ændringer

    hugo serve

  5. For at opbygge dig statiske html-websted inde i webstedsmappen skal du køre følgende kommando

    hugo

  6. Skub din gh-sider-gren til GitHub

  7. Konfigurer GitHub-projekt for at aktivere sider

    • Se Konfiguration af en udgivelseskilde til dit GitHub-sidewebsted - GitHub Docs
    • Markeret gh-sider gren og /docs mappe

Opdater hjemmesidens billedbadge

Hvis du vil tilpasse billedet på startsiden til badget Status: Offentlig prøveversion, gør jeg følgende:

  1. Klon svg-badges repo

    git clone https://github.com/anouarhassine/svg-badges.git
cd svg-badges

  2. Installer moduler

    npm install

  3. Start webserveren for at generere badges

    npm run start

  4. Generer badge

    http://localhost:9000/static/Status-Public%20Preview-Green

  5. Download svg-badget

  6. Brug inkscape til at redigere eksisterende svg og gemme resultater

  7. Upload nyt billede til mappen static \images\illustrations

  8. Ændre config.yaml hero-billedet

    params:
    hero:
        image: illustrations/worker-public-preview.svg

Spørgsmål og svar

Spørgsmål Hvorfor blev Hugo valgt?

Hugo er en populær statisk webstedsgenerator, der tillader indhold af Automatiseringssæt til Power Platform startdokumentation, der skal transformeres til statisk HTML, der kan hostes på GitHub-sider

Spørgsmål Hvorfor valgte du ikke en anden statisk webstedsgenerator?

Det centrale Power CAT-team havde tidligere erfaring med at bruge Hugo

Spørgsmål Hvorfor blev Microsoft Forms ikke brugt til spørgsmål?

Et designmål var at integrere spørgeprocessen direkte i indholdet.

Spørgsmål Hvorfor GitHub-sider til hosting af indhold?

Kildekoden til Automatiseringssæt til Power Platform findes allerede på GitHub, og understøttelsen af de oprindelige GitHub-sider var et valg af, hvor indholdet skulle hostes.

Spørgsmål Hvorfor er dette indhold ikke tændt http://learn.microsoft.com?

  • Efterhånden som indholdet modnes til almindeligt genanvendelig vejledning, kan det migrere til https://learn.microsoft.com

  • Et vigtigt designmål er aktiveret af GitHub-hosting

    • Tillad aktivt samfundsbidrag

    • Fremme plejeprocessen i Center of Excellence, så dokumentation kan genbruges af kunder og partnerfællesskab

Spørgsmål Hvorfor anvendes tilgangen ikke på andre Power CAT-projekter?

Den Automatiseringssæt til Power Platform eksperimenterer med denne dokumentationskanal for at komplimentere og linke til vores eksisterende Læringsindhold. Baseret på feedback og resultat af dette eksperiment vil vi evaluere, om andre Power CAT-styrede projekter vil vedtage en lignende tilgang.

Spørgsmål Hvordan kan jeg se problemer med åben dokumentation?

Du kan besøge vores Problemer med åben dokumentation side

Spørgsmål Hvordan rejser jeg en anmodning om en ny dokumentationsfunktion?

Opret en ny Anmodning om funktion