Richtlijnen voor het opstellen van richtlijnen

In de volgende secties worden richtlijnen en opmerkingen voor het schrijven van startdocumentatie beschreven.

Richtsnoeren

In de volgende secties worden technische, ontwerp- en resultaatgebaseerde richtlijnen voor het schrijven van bijdragen beschreven

Doelen

Bij het samenstellen van onze documentatie is het belangrijk om na te denken over hoe we onze lezers in staat stellen om Val in de put van succes.

Brad Abrams gedefinieerd De put van succes in 2003 als

De put van succes: in schril contrast met een top, een piek of een reis door een woestijn om de overwinning te vinden door middel van vele beproevingen en verrassingen, we willen dat onze klanten gewoon vervallen in winnende praktijken door gebruik te maken van ons platform en onze frameworks. In de mate dat we het gemakkelijk maken om in de problemen te komen, falen we.

Overweeg gezien dit doel het volgende:

Zorg voor een “no cliffs experience”
- Beheerders en centrale governanceteams helpen bij het maken van een selfservicemodel voor het gebruik van Automation Kit voor Power Platform
- Gebruikers toestaan gebruik te maken van ontwikkelomgevingen om in handen te krijgen als een centrale omgeving niet beschikbaar is en ze functies willen hebben voordat een test of productie-implementatie van de Automation Kit voor Power Platform
- Bespreek het gebruik van proefomgevingen met eenvoudige installatie om in handen te krijgen met de Automation Kit voor Power Platform
Zorg voor een kanaal voor feedback. Geef opties voor klanten om input te geven over wat we kunnen verbeteren

Bronbeheer

Je hebt afgerond Documentatie stappen om wijzigingen naar de GitHub-opslagplaats te downloaden en te pushen
Nieuwe wijzigingen worden gepusht naar een nieuwe vestiging en hebben een pull-aanvraag om wijzigingen te beoordelen
Alle documentatie moet bestaan uit markdown, JSon of statische assets die versiebesturingselementen kunnen zijn en kunnen worden beoordeeld met behulp van het standaard pull-aanvraagproces

Ontwerprichtlijnen

Hoofdpagina

Zorg voor een duidelijke titel en ondertitel die het doel van de starterservaring schetst
Geef een call-to-action om andere gerelateerde gebeurtenissen op te nemen. Schrijf je bijvoorbeeld in voor Kantooruren.
Koppeling naar de actie Aan de slag als primaire actie om nieuwe gebruikers aan boord te helpen
Secundaire actie om deel te nemen aan kantooruren om een community van gebruikers op te bouwen
Tegels van veelvoorkomende acties opnemen
Overzichtslijst met functies die gebruikers helpen bij het beheren van hyperautomatieprojecten
Voettekstnavigatie voor algemene koppelingen.

Lees de Site configuratie voor meer informatie over het configureren van de startpagina.

Hergebruik

Gebruik hugo-lay-outs om een nieuw thema op te geven of het huidige thema te overschrijven door inhoud in de map site\layouts te plaatsen
Als u lay-outs wijzigt, moet statische HTML op veel hostinglocaties kunnen worden opgenomen. Bijvoorbeeld
- GitHub-pagina’s
- Power-pagina’s
- Punt delen
- Statische Azure-websites
De aanpak kan door partners of klanten worden gebruikt als een sjabloon om “documentatiepakketten” te bouwen om de nuture-fase van Automation Kit voor Power Platform documentatie
De mogelijkheid bieden voor meerdere gebruikers van de documentatie (bijv. Teams van klanten en partnercentra)
Toestaan dat door de gebruiker geleverde inhoud wordt opgenomen
Upgradeproces toestaan waarmee nieuwe wijzigingen kunnen worden opgehaald uit Automation Kit voor Power Platform starter documentatie

Markdown-pagina’s

U kunt gebruik maken van Visual Studio-code om de markeringsbestanden te bewerken
Markdown-bestanden moeten zich in de map /site/content bevinden
Elk markdown-bestand moet een gemeenschappelijke koptekst op elke pagina bevatten

title: Sample page
description: Automation Kit sample page
sidebar: false
sidebarlogo: fresh-white
include_footer: true

Markdown-bestanden moeten shortcodes gebruiken om JavaScript in te sluiten

shortcodes

Shortcodes bieden de mogelijkheid om dynamische inhoud op te nemen in een afwaarderingspagina. U kunt meer lezen over shortcodes van de Hugo shortcode documentatie

Dit project bevat ook extra shortcodes

Inhoudsopgave

Voeg de Inhoudsopgave het volgen van shortcode naar uw markdown om een tabel met inhoud van markdown-headers op te nemen in de pagina omringd door {{ en }}

<toc/>

Vraag

Neem een reeks vragen op uw pagina op, omringd door {{ en }}

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

Parameters:

naam De naam van het JSon-bestand met vragen die u wilt importeren. Lezen Vragen voor meer informatie over de bestandsindeling van de vraag
volbracht De tekst die moet worden weergegeven wanneer de vragen zijn voltooid
showNavigatieKnoppen true/false-waarde naar de navigatieknoppen Volgende/Terug/Voltooid

Externe afbeelding

Een afbeelding van een formaat van een externe bron opnemen in uw pagina omringd door {{ en }}

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

Parameters:

Src Het bronpad naar de te importeren afbeelding
grootte De grootte in pixels om het formaat van de bronafbeelding te wijzigen in
Sms De alternatieve tekst die u bij de afbeelding wilt opnemen

Notities

GitHub-pagina’s instellen

De volgende stappen werden gebruikt om de GitHub-pagina’s voor de site in te stellen

Controleer de documentatietak
```
git checkout gh-pages
```
Hugo extended is geïnstalleerd
- U kunt ook installeren met chocolatey op ramen
```
choco install hugo-extended -confirm
```
Wijzigen in sitemap
```
cd site
```
Test uw wijzigingen
```
hugo serve
```
Als u de statische html-site in de sitemap wilt bouwen, voert u de volgende opdracht uit
```
hugo
```
Push je gh-pages branch naar GitHub
GitHub-project instellen om Pages in te schakelen
- Zie Een publicatiebron configureren voor uw GitHub Pages-site - GitHub-documenten
- Geselecteerde gh-pages branch en /docs map

Afbeeldingsbadge voor startpagina bijwerken

Als u de afbeelding van de startpagina wilt aanpassen naar een status: Badge voor openbare voorvertoning Ga als volgt te werk:

Kloon de svg-badges repo

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

Modules installeren
```
npm install
```
Start de webserver om badges te genereren
```
npm run start
```

Badge genereren

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

Download de svg badge
Gebruik inkscape om bestaande svg te bewerken en resultaten op te slaan
Nieuwe afbeelding uploaden naar de map statisch\afbeeldingen\illustraties

De afbeelding config.yaml hero wijzigen

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

Vraag en antwoord

Vraag Waarom is Hugo geselecteerd?

Hugo is een populaire statische sitegenerator die inhoud van de Automation Kit voor Power Platform starterdocumentatie die moet worden omgezet in statische HTML die kan worden gehost in GitHub-pagina’s

Vraag Waarom hebt u niet een andere statische sitegenerator geselecteerd?

Het kern power CAT-team had eerdere ervaring met Hugo

Vraag Waarom is Microsoft Forms niet gebruikt voor vragen?

Een van de doelen van het ontwerp was om het vraagproces direct in de inhoud te integreren.

Vraag Waarom GitHub-pagina’s om inhoud te hosten?

De broncode voor de Automation Kit voor Power Platform bestaat al op GitHub en de ondersteuning van de native GitHub-pagina’s was een keuze van waar de inhoud moest worden gehost.

Vraag Waarom is deze inhoud niet ingeschakeld http://learn.microsoft.com?

Naarmate inhoud volwassener wordt tot algemeen herbruikbare begeleiding, kan deze migreren naar https://learn.microsoft.com
Een belangrijk ontwerpdoel wordt mogelijk gemaakt door GitHub-hosting
- Sta actieve bijdrage van de community toe
- Stimuleer het Nuture-proces van center of excellence, zodat documentatie kan worden hergebruikt door klanten en de partnergemeenschap

Vraag Waarom wordt de aanpak niet toegepast op andere Power CAT-projecten?

De Automation Kit voor Power Platform experimenteert met dit kanaal van documentatie om onze bestaande te complimenteren en te koppelen aan onze bestaande Leerinhoud. Op basis van de feedback en de resultaten van dit experiment zullen we evalueren of andere door Power CAT beheerde projecten een vergelijkbare aanpak zullen volgen.

Vraag Hoe zie ik problemen met openstaande documentatie?

U kunt onze Problemen met open documentatie bladzijde

Vraag Hoe kan ik een nieuwe aanvraag voor een documentatiefunctie indienen?

Een nieuwe maken Functieverzoek