A guide to annotating an article4/6/2024 Formatting calloutsĮach callout starts with text indicating the type of callout (e.g. There are three types of in-content callouts: notes, warnings, and danger notices. Do not include more than two bullet points in a callout. Use callouts sparingly for high-value information - do not include general information, permissions, or prerequisites in callouts. We use standard formatting and colors for different types of callouts across doc sets. Avoid: Triggered when a user updates which repositories a codespace can access.Ĭallouts highlight important information that customers need to know.Avoid: An organization owner disabled a two-factor authentication requirement for the organization.Use: Secret scanning was enabled for all new repositories.Use: The visibility of a repository was changed.Do not begin the sentence with phrases that are already implied by the context of the article, such as "Triggered by." When writing the description for an audit log event, describe the event that took place in a way that applies to all versions, using past tense and passive voice. " Audit log events for your enterprise" in the GitHub Enterprise Cloud documentation." Audit log events for your organization".We document each of the events that may appear in the audit logs for each type of account: user, organization, and enterprise. If a reviewer asks about it, we're prepared to discuss the decision. When a question specific to help documentation isn’t covered by the style guide, we think it through using these principles, then make a decision.When making a style or structure decision, we consider the flow of information within the unit of content and the context of the information.Consistency and grammatical correctness are important, but not as important as clarity and meaning.To scale the style guide as our team and documentation sets grow, and to create high-quality, meaningful content that serves users, we focus our attention on high-impact, high-value scenarios rather than attempting to comprehensively cover every style question.We're flexible and open to change while maintaining consistency. Decisions aren’t about what’s right or wrong according to the rules of grammar or the style guide, but about what’s best for our users.Guidelines should be easy to apply to a range of scenarios. For markup specific to source content on, see " Using Markdown and Liquid in GitHub Docs." For any questions about the GitHub brand, see our " GitHub Brand Guide." The GitHub Docs approach to style For general style questions or guidance on topics not covered here, see the Microsoft Style Guide. Note: These guidelines are specific to GitHub's documentation.
0 Comments
Leave a Reply.AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |