jens/flipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Under the Hood - Part 4

Browse Source 
Summary:
This diff includes minor changes to the pages within the Under the Hood section of Flipper Docs.

The page Creating Plugins -> Desktop Plugin APIs -> QPL Linting -> Building a Linter is now removed from the sidebar.

Reviewed By: lblasa

Differential Revision: D41533283

fbshipit-source-id: 63e50210815fe2b67ea54991eb8a7bc16e04e1be
This commit is contained in:
Kevin Strider
2022-11-28 03:46:26 -08:00
committed by Facebook GitHub Bot
parent 56b717c197
commit ced04c7cec
5 changed files with 321 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
docs/internals/documentation-formatting.mdx
View File

@@ -1,35 +1,40 @@
---
id: documentation-formatting
title: Formatting Tips
title: Markdown Formatting
description: Tips and guidelines for Mardown used within Static Docs documentation
keywords:
- flipper website formatting
- flipper docs formatting
---
This page provides recommendations on the use of a variety of Markdown features that help you create properly formatted documentation.
## Subsections
For tips and guidelines on when to use the same tools, and several others, see the [Writing Guide](documentation-writing-guide.mdx).
Use regular H2..H6 markdown headings for subsections.
## Structural format
```markdown
## Level 2 title
### Headers
### Level 3 title
* Start each main section with a level 2 header.
* Sub-sections should follow a hierarchical structure and should use header levels 3 to 5.
#### Level 4 title
**Markdown Example**:
The following example Markdown shows how to use headers.
```bash
## Level 2 header
### Level 3 header
#### Level 4 header
##### Level 5 header
```
```diff
- **Testing complex components**
+ ### Testing complex components
```
## Markdown tools
:::tip
* The page title will implicitly be formatted with H1, so start with H2.
* Headings appear in the Table of Contents, which gives the reader an overview of the page and assists with navigation.
:::
## Backticks
### Backticks
Use Markdown backticks ( \` \), to provide emphasis for items such as file names, classes, methods, parameters, and expressions.
@@ -91,26 +96,20 @@ addPlugin({
For more code blocks features, such as line highlighting, see the Docusaurus [Code blocks](https://docusaurus.io/docs/markdown-features/code-blocks) document.
## Links
### Links
Docusaurus supports regular Markdown links with absolute URLs, relative URLs, and relative file paths.
Avoid using bare URLs in your documentation. Instead, use referenced hyperlinks, as shown in the following table.
However, due to the [trailing slash issue](https://github.com/facebook/docusaurus/pull/4908), it's strongly recommended to link to page files (including their extension) instead of the page's URL.
```diff
- Don't link to markdown page URLs: [Create a page](create-a-page).
+ Create links using full file names: [Create a page](create-a-page.md).
other text
- [Create internal only document](contributing-documentation#internal-only-content]
+ [Create internal only document](contributing-documentation.md#internal-only-content]
```
| Type | Code | Displays as |
| :-- | :-- | :-- |
| **Bare URL** | `Upload the video to Pixelcloud at https://www.internalfb.com/intern/px/search` | Upload the video to Pixelcloud at https://www.internalfb.com/intern/px/search |
| **Referenced** | `Upload the video to [Pixelcloud](https://www.internalfb.com/intern/px/search)`| Upload the video to [Pixelcloud](https://www.internalfb.com/intern/px/search) |
:::tip
Don't use absolute or internal docs links.
With relative links, the Static Docs engine will automatically use the right host depending on whether docs are accessed externally or internally.
Notice the use of square brackets around 'PixelCloud' in the referenced hyperlink.
:::
## Tabs
### Tabs
To organize content in tabs, Docusaurus provides the `Tabs` React component:
@@ -120,16 +119,16 @@ import TabItem from '@theme/TabItem';
<Tabs
groupId="platform"
defaultValue="iOS"
defaultValue="kotlin"
values={[
{label: 'iOS', value: 'ios'},
{label: 'Android', value: 'android'},
{label: 'Kotlin', value: 'kotlin'},
{label: 'Java', value: 'java'},
]}>
<TabItem value="ios">
Information about Flipper on iOS.
<TabItem value="kotlin">
Information about using Kotlin with Flipper.
</TabItem>
<TabItem value="android">
Information about Flipper on Android.
<TabItem value="java">
Information about using Java with Flipper.
</TabItem>
</Tabs>
```
@@ -140,16 +139,16 @@ import TabItem from '@theme/TabItem';
**Result:**
<Tabs
groupId="platform"
defaultValue="ios"
defaultValue="kotlin"
values={[
{label: 'iOS', value: 'ios'},
{label: 'Android', value: 'android'},
{label: 'Kotlin', value: 'kotlin'},
{label: 'Java', value: 'java'},
]}>
<TabItem value="ios">
Information about Flipper on iOS.
<TabItem value="kotlin">
Information about using Kotlin with Flipper.
</TabItem>
<TabItem value="android">
Information about Flipper on Android.
<TabItem value="java">
Information about using Java with Flipper.
</TabItem>
</Tabs>

66
docs/internals/documentation-standards.md Normal file
View File

@@ -0,0 +1,66 @@
---
id: documentation-standards
title: Flipper Docs Standards
sidebar_label: Flipper Docs Standards
description: Provides a set of standards requirements to persist documentation standards
keywords:
- Flipper docs standards
- Flipper docs rules
---
import useBaseUrl from '@docusaurus/useBaseUrl';
## Key standards
The Flipper Docs team is committed to writing docs that serve users. To measure and maintain satisfactory documentation quality, the following key standards are used:
| [Completeness](#completeness) | [Discoverability](#discoverability) | [Accessibility](#accessibility) | [Accuracy](#accuracy) |
|:--|:--|:--|:--|
| Is the information sufficient to give the reader a good understanding or to provide a solid solution to a problem? | If the information exists, is it easy to find? | Is the information accessible to readers of different capability? | Is the information accurate and up to date? |
To help you achieve each of these standards, several points for consideration are listed in the following sub-sections (or you can select a column header to link to its sub-section).
### Completeness
Completeness is determined by how many questions, and the type of questions, the reader may have after reading your document. For example, if after reading a Flipper document on 'getting help and providing feedback', the reader asked the question "Where do I go if I'm a noob?" then the document might not be complete.
To increase your document's completeness, consider the following:
* Limit Assumptions.
* Trade-offs and limitations of APIs and approaches should be discussed openly.
* Where possible, describe alternatives to what you're describing: understanding the available options empowers people to feel confident in their choices.
* Give tips you think are particularly useful.
* The user shouldn't have to navigate to different documentation sources (such as Wiki pages and posts) to gain a core understanding.
* Explain what success looks like.
* The discussion of a technical topic shouldn't be in the 'Getting Started' section.
* Is each step explained, or does it rely on other knowledge?
* Empathize with the reader. Consider questions such as: "*Are they trying to learn how to do something?*" and "*Has something gone wrong and they're trying to figure out if a solution is possible?*"
### Discoverability
Discoverability is the degree to which a piece of information (instruction, guideline, code snippet, and so on) can be found within the Flipper Documentation website.
To improve your document's discoverability, consider the following:
* Add appropriate keywords to your file. The keywords are used by Static Doc's search tool.
* Is the information easy to find. Test for keyword searches to see if and where in the result list your documentation is listed.
* Consider the placement of the file (if you're adding a new one).
### Accessibility
Accessibility is the measure of how easy it is for users of different capability to read, understand and navigate your documentation.
To improve your document's accessibility, think about the following:
* Is non-standard terminology fully defined before being used (this includes the use of abbreviations).
* Is it easy to understand and apply the documented information?
* The most effective medium (words, diagrams, images, videos, examples, or a combination).
### Accuracy
Accuracy is determined by how relevant, correct, and up to date the content of your documentation is.
To ensure your document's accuracy, think about the following:
* Ensure that all 'Live' code samples are relevant to the topic being covered and provide appropriate output.
* Explain the relevant aspects of the snippet functionality clearly.
* When making any changes to procedure, architecture, or code, make the documentation of those changes part of the change request.

252
docs/internals/documentation-writing-guide.mdx
View File

@@ -1,67 +1,139 @@
---
id: documentation-writing-guide
title: Writing Guide
description: Provides tips and guidelines for effective writing.
keywords:
- flipper website writing tips
- flipper docs writing tips
- flipper documentation guidelines
---
import useBaseUrl from '@docusaurus/useBaseUrl';
This page contains tips and guidelines on how to create effective documentation that will be valued by your target reader (a measure of its success).
To assist you in writing your documentation, this page contains tips and guidelines on how to create effective documentation that is valued by your target reader (a measure of its success).
We use StaticDocs, which is based on [Docusaurus](https://docusaurus.io/), for the Flipper documentation website.
The [StaticDocs](https://www.internalfb.com/intern/staticdocs/staticdocs/) homepage is an excellent starting point for information.
Flipper uses StaticDocs, which is based on [Docusaurus](https://docusaurus.io/), for the Flipper documentation website. The [StaticDocs](https://www.internalfb.com/intern/staticdocs/staticdocs/) homepage is an excellent starting point for information.
## Why Documentation Is Needed
Some of the benefits of documentation include:
* It's immediately available from the [Flipper Documentation website](https://www.internalfb.com/intern/staticdocs/flipper/)
* Reduces the number of requests for support.
* Provides a permanent record of your valuable knowledge.
* **Immediate availability** - from the easily accessible [Flipper Documentation website](https://www.internalfb.com/intern/staticdocs/flipper/)
* **Fewer support requests** - the more information that's available online, the fewer the number of support requests. Also, colleagues that raise requests can be directed to the documentation website, which frees up the time of the person being asked.
* **Knowledge base** - provides a permanent record of Flipper knowledge, rather than it being isolated to one or more specialists.
By making documentation part of your work routine, it becomes less of a burden: the more you write, the easier it gets.
## Getting Started
## Adding or editing content
Often, the most difficult aspect of creating documentation is figuring out how to get started. The following five steps provide some guidance that may help.
You may be creating content for a new document or updating the content of an existing document. Whatever the reason, there are two key points to consider before you make any changes:
1. **Consider your target reader** - reflect on questions similar to the following:
1. [Tone of voice](#tone-of-voice) - this is the 'voice style' used to communicate the content to the reader.
2. [Documentation style](#documentation-style) - this is the tools used to communicate the content to the reader, such as bullet points, images, tables, bold text, headers, videos, and so on. The trick is knowing when to use them and how to use them effectively.
* Why does the reader need this documentation?
* What is the reader's level of expertise?
* What is the best way to present the information to the reader?
Both of these key points are detailed in the following sub-sections.
2. **Create a document outline** - create a list of topics you would like to cover that help you to explain the main subject matter. Bearing in mind your target reader, put the topics into the order in which you think they make the most sense: this may involve grouping topics and noting any links between them.
3. **Create a new page** - when relevant, create a new page (.md file) in the correct repository folder, making sure you insert the required metadata.
4. **Convert topics into headers** - once you've organised the topics, convert them into headers for sections (topic groups) and sub-sections (topics). See below for details of how to use [Headers](#headers).
5. **Create an introduction** - write a brief introduction to your documentation, which states its purpose and an overview of its contents. Your reader will use this to save time and to determine if the document contains the required knowledge or not.
## Tone of voice
After taking these five steps, you'll have a basic structure for your documentation! The next step is to write the core content, that is, the information that is contained by each header.
:::note Important
## Creating the Core Content
The content of any material you create for any aspect of Meta's documentation must fully comply with Meta's values, policies, and initiatives, and must incorporate Meta's principles of diversity, equity and inclusion.
Using the right tone of voice can make your document interesting, engaging, and memorable. The remainder of this page contains guidelines on which tone to use and how to use a range of Markdown features.
For details, see the following:
### Tone of Voice
* [Meta People Portal](https://www.internalfb.com/intern/people/portal/facebook-inc).
* [Building Better: The Meta Code of Conduct](https://s21.q4cdn.com/399680738/files/doc_downloads/governance_documents/2022/06/FB_CoC_EXTERNAL_en_EN_Update_Final-6_2-FINAL-ua.pdf).
:::
'Tone of voice' is the style that you use to communicate the information contained within your documentation, it's like tone of voice you choose to use when speaking with someone. The following guidelines may help you to adopt the right tone of voice in your documentation.
Consider how you'd explain a work-related task to a colleague; the words you'd use and the manner in which you'd say them. Following are some points to consider, which will help you to adopt the write 'tone of voice' in your documentation:
* **Write in the Second Person (You/Your/Yours)** - the main benefit is that it increases the readers' sense of involvement in the content and promotes a friendly tone by addressing your reader directly. As a result, your document's reader will find the content more engaging, easier to remember, and easier to understand.
**Note**: this page has been written using the second person.
* **Semi-formal** - imagine talking to a colleague whom you've just met in the workplace. When explaining something to them, you wouldn't want to be too formal, but you'd also like to appear friendly.
* **Professional** - all communication must follow Meta company guidelines and policies and incorporate the principles of diversity, equity and inclusion.
* **Descriptive** - don't go off-topic: keep to the topic that is relevant to the page/section. Textual information should be well-explained but not excessive. Lists, images and videos can be used to reduce large blocks of text (see [Markdown Formatting](documentation-formatting.mdx)).
* **Engaging** - the correct use of pronouns can aid comprehension and help to keep the reader engaged and comprehension (see below).
* **Use First-Person Plural Pronouns (We/Our) sparingly** - the main reason is that such pronouns emphasise the writer's team or organisation rather than the reader, which goes against the principle of writing in the second person. The use of 'we' and 'our' can cause distraction or irritation to the reader because the reader might not know which group of people are being referred to with 'we' or 'our'. 'We' could even mean the writer and the reader!
### The magic of pronouns
The correct use of pronouns can increase the reader's engagement, enjoyment, and comprehension of the information in your documentation. Following are some guidelines on when to use particular pronouns (it does matter):
* **Use the pronouns 'You', 'Your', and 'Yours'** - the main benefit of using them is that it increases the reader's sense of involvement in the content and promotes a friendly tone by addressing the reader directly (think about how you'd explain something complex to your colleague). As a result, your page's reader will find the content more engaging, easier to remember, and easier to understand. These pronouns are especially useful when you want to detail a series of steps that the reader must follow.
* **Use the pronouns 'We' and 'Our'** - the main reason for their use is that they emphasise the reader's team or organisation, which gives the reader a sense of community and team spirit. These pronouns are especially useful when you want to describe something that involves the Flipper team, such as the reasons for the decision to use a particular technology or how the reader's actions can benefit the team.
* **Don't use the pronouns 'I' and 'My'** - the main reason is that it emphasizes the writer rather than the reader. Also, it may cause confusion, reduce engagement, or be the source of annoyance as the reader may not know the identity of the writer.
### Spelling and grammar
Bad spelling and grammar can have a negative effect on the tone of voice in your document (making it irritating to read and difficult to understand).
The problem is that we all make unintentional spelling and grammar errors when writing. Fortunately, there are three steps you can take to reduce (or, hopefully, remove all) those errors:
1. **Read it** - when you think you've finished, read though the content and make the appropriate corrections.
2. **MS Word it** - use the spelling and grammar checker to identify any errors.
3. **Review it** - before your page is published, it will be reviewed as part of its Diff lifecycle. Make sure you consider all of the changes suggested by the Reviewers.
This is not going to be 100% effective every time, but it will definitely help to get as close to 100% as possible.
## Documentation style
Documentation style involves two areas of interest:
* **Structural Format** - this includes the format of the page title and the headers and includes topics such as:
* How many words to use.
* How to capitalise.
* How to improve the discoverability of the content.
* **Documentation Tools** - this includes the following:
* When and how to use the available tools (such as bullet points, tables images, videos, and much more).
* How to format the content for the selected tool.
## Structural format
### Page title
The title provides an at-a-glance summary of a page's content. It is also used in the SideBar so assists with navigation of the Flipper Documentation website. Consider the following guidelines before choosing a page title.
* **Short but descriptive** - the title should be short but also descriptive enough to convey the main topic of the page's content.
* **Capitalization** - use the 'Title' case associated with the [Chicago Manual of Style (17th edition)](https://www.chicagomanualofstyle.org/home.html). For details of a helpful online tool, see [Header and title capitalization tool](#header-and-title-capitalization-tool), below.
* **Titles should be unique** - use a title that is not used elsewhere within the Flipper Documentation website.
### Headers
Good documentation is split into a series of sections that are logically structured and cover the subject matter. Headings are used for the document's Table of Contents, which provide the reader with an outline of the document and assist with navigation.
Good documentation is split into a series of sections that are logically structured and cover the subject matter. Headings are used for the document's Table of Contents, which provide the reader with an outline of the document and assists with navigation.
* **Headers indicate document structure** - start each main section with a level 2 header. Sub-sections (header levels 3 to 6) should follow a hierarchical structure and be associated with, or relevant to, their parent header.
* **Headers indicate document structure** - start each main section with a level 2 header. Sub-sections (header levels 3 to 5) should follow a hierarchical structure and be associated with, or relevant to, their parent header.
* **Keep headers short** - while keeping your headers as short as possible, make sure they contain enough words to indicate the information contained within the section/sub-section.
* **Keep Headers unique** - consider how a header will be listed in the result set of a search from the Static Docs website.
* **Capitalisation of headers** - capitalisation should be consistent throughout all Flipper documentation. Headers should be capitalised according to the headline style defined in the [Chicago Manual of Style (17th edition)](https://www.chicagomanualofstyle.org/home.html).
* **Capitalisation of headers** - use the 'Sentence' case associated with the [Chicago Manual of Style (17th edition)](https://www.chicagomanualofstyle.org/home.html). For details of a helpful online tool, see [Header and title capitalization tool](#header-and-title-capitalization-tool), below.
* **Use Blank Lines** - make sure there is one blank line between a heading and the text in its section/sub-section.
:::tip
To ensure you're complying with the Chicago Manual of Style, go to the online tool [Capitalize My Title](https://capitalizemytitle.com/style/Chicago/), select the Chicago tab and enter your heading. As you enter the heading, the tool automatically converts it to the Chicago style.
#### Header and title capitalization tool
To assist with the capitalization of your page's title and headers, go to the online tool [Capitalize My Title](https://capitalizemytitle.com/style/Chicago/), then:
* **For the title** - select the 'Chicago' tab and click the 'Title Case' option.
* **For headers** - select the 'Chicago' tab and click the 'Sentence case' option.
As you enter the title/header, the tool automatically converts it to the selected style, which you can then copy/paste into your editor.
#### Markdown code
For examples of using Markdown for headers, see [Markdown Formatting](documentation-formatting.mdx#headers)
## Markdown tools
### Code snippets
Code examples are one of the best ways to help your readers take their understanding to the next level by providing them with something they can actually view and experiment with on their own.
:::note
Remember that a snippet is 'a small part or piece of a thing' so keep your snippet as short as possible and relevant to the section in which it's located.
:::
When providing code snippets, first create an example in the Flipper shell and then directly reference that example in your documentation. This enables the Flipper website to **ensure that code in its documentation always stays up-to-date and functional**
Make sure there is one blank line between the code snippet and any surrounding text.
#### Markdown code
For an example of using Markdown for code snippets, see [Markdown Formatting](documentation-formatting.mdx#code-snippets)
### Images
Images includes pictures, diagrams, and screenshots.
@@ -70,30 +142,82 @@ The well-known adage "*A picture is worth a thousand words.*" is true but must b
* **No sensitive or personal data** - if you're taking a screenshot that features data, ensure it is test or sample data.
* **Use a lossless format** - PNG and SVG files are ideal for websites and PDFs, other formats may look blurred.
* **Use a transparent background** - you don't know what colour background your reader will use when reading your documentation. By using a transparent background, you avoid potential colour clashes and unwanted image borders.
* **Avoid coloured borders and shadows** - again, you don't know what colour background your reader will use when reading your documentation. A coloured border or a shadow might look great against the colour you are using but could look ugly against a different background.
* **Size for readability** - there's little purpose in using any type of image if the text within it can't be read or needs a magnifying glass. Consider splitting your image into two or more images and show how they are connected. If using a screenshot, zoom in on a specific area of the screen and provide context.
* **Be color-consistent** - use the same colour and style for callouts and annotations throughout your documentation.
* **Consider dark mode backgrounds** - use of a dark mode is becoming increasingly common. With this in mind, test your image using light and dark mode; as a result, you may need to replace black/dark grey colours with pastel-coloured alternatives.
* **Use a transparent background** - by using a transparent background, you avoid potential color clashes and unwanted image borders caused by your reader's use of a colored or themed background.
* **Avoid colored borders and shadows** - a colored border or a shadow might look great against the color you are using but could look ugly against a differently colored background.
* **Consider dark mode backgrounds** - when relevant, test your image using light and dark mode; as a result, you may need to replace black/dark grey colors with pastel-colored alternatives (note: this does not apply to screenshots).
* **Size for readability**:
* There's little purpose in using any type of image if the text within it can't be read or needs a magnifying glass.
* If your image is large, consider splitting into two or more images and show how they are connected.
* If using a screenshot, zoom in on a specific area of the screen and provide context rather than capturing the whole screen.
* **Be consistent** - use the same color and style for callouts and annotations throughout your documentation.
* **Refer to the image** - mention the image within the accompanying text. Such as "*As shown in the following image...*", or "*The image below provides an overview of...*"
:::tip
Keep in mind that images are meant to complement text, not replace it. Though a picture may be worth a thousand words, the reader still needs the detail contained within the text.
:::
### Videos
### Latin abbreviations
Videos are an effective method to present a lot of information to the reader. However, just like images, the use of videos must be accompanied by knowledge of how to use them effectively. Following are guidelines for the use of video in your documentation.
The use of some Latin abbreviations (such as 'e.g.', 'etc.', 'i.e.', 'et al.', and so on) should be avoided for the following reasons:
* **Watch the video** - before you use the video in your documentation, watch it to check that its good quality, relevant to the section in which it's located, and provides sufficient information.
* **Keep the content concise** - the content of the video should be limited to the specific purpose for which it is being used. For example, if a video is being used to illustrate configuration of a component, it should contain just that process.
* **Refer to the video** - mention the video within the section in which it's being used. Also, state the length of the video. For example: "*The above video demonstrates the slightly different 'Hg: Show Head Changes' command*".
* **State the length of the video** - if the length of the video is not shown in the video object, state it in the text. For example, "*The above 11-second video demonstrates the slightly different 'Hg: Show Head Changes' command*".
* Readers of the documentation may not use English as their 'first' language and may be unaware of the meaning of Latin abbreviations.
* Often, when used, Latin abbreviations are not correctly punctuated, which detracts from the professional tone of the page's content.
:::tip
When deciding to use a video, keep in mind that it takes much more time to produce a video than to change some text. A small change to a UI or a process is relatively easy to change in text. The same change in a video may mean it needs to be replaced or removed, which, ultimately, involves much more work.
When tempted to use the Latin abbreviations shown in the following table, consider using the English equivalent.
| Latin | English Equivalent
|:--|:--|
| e.g. | for example |
| et al. | and colleagues / associates / team members |
| etc. | and so on / and the rest |
| i.e. | that is |
| N.B. | Note |
:::note
**Key point**: whenever possible, use plain, easy-to-understand English in your documentation.
:::
### Links
Within Flipper Docs, links are usually text-based and can be used to navigate your readers to several types of link targets, such as the following 'good' links:
* For information on the type of links to avoid, see [Bad links](#bad-links), below.
* For examples of using Markdown for headers, see the [Markdown Formatting](documentation-formatting.mdx#headers) page.
* To learn all about Litho, see the [Litho Documentation](https://www.internalfb.com/intern/staticdocs/litho/docs/intro/motivation/) website.
As can be seen in the link examples above, a link consists of the parts shown in the following table (but not necessarily in the same order).
| Link part | Using the first example, above |
| :-- | :-- |
| Leading Phrase | "For information on the type of links to avoid, see" |
| Target description | [Bad links] |
| (Optional) Location | ", below" or "website"|
| Target | (#bad-links) or a URL|
:::tip Tips
* **Navigation** - tell your readers where they are going, especially if the link takes them away from the Flipper Docs website (see [Bad links](#bad-links), below).
* **Test** - check that your links do reach the expected target.
* **Access** - keep in mind that some readers may not have access to certain pages or domains.
* **Backticks** - don't use backticks in links as it changes the link's appearance. It has to look like a link for the user to know they can click on it.
:::
#### Bad links
It's worth remembering that the reader won't know beforehand where a link is taking them unless it's stated (or at least suggested) in the 'Target description' or the 'Location'.
Therefore, it's not a good idea to use links such as the following:
* For information on the type of links to avoid, see [below](#markdown-code).
* Click [here](documentation-formatting.mdx#headers) to see examples of using Markdown for headers.
* To learn all about Litho, click [here](https://www.internalfb.com/intern/staticdocs/litho/docs/intro/motivation/).
'Bad' links could lead to navigation confusion, frustration, and loss of comprehension.
#### Markdown code
For additional guidelines on using Markdown for links, see [Markdown Formatting](documentation-formatting.mdx#links).
### Lists
If the information you wish to communicate involves a series of steps, follows a defined procedure, or indicates preference or ranking, use a [numbered list](#numbered-list), which is also known as an 'ordered' list.
@@ -103,12 +227,14 @@ If the order of items in the list is irrelevant, use [bullet points](#bullet-poi
#### Bullet Points
* **Be concise but effective** - use as few words as possible but make sure the meaning is not lost.
* **Capitalise the first word** of each bullet.
* **Use emphasis** - where possible, emphasise the beginning of the bullet points to give the reader the chance to skim through easily but still get a basic understanding of the content of the list.
* **Capitalise the first word** - do this for each bullet.
* **One sentence per bullet point** - try to stick to one sentence per bullet point.
* **Use emphasis** - where possible, emphasize the beginning of each bullet point to give the reader the chance to skim through easily but still get a basic understanding of the content of the list.
* **Use sentences or fragments, not both** - within a single list, avoid using bullets that are full sentences mixed with other bullets that are just sentence fragments, phrases, or names.
* **Punctuate consistently:**
* If at least one bullet is a sentence, end all bullets with a full stop. Don't end a bullet with a semicolon (;).
* If at least one bullet is a sentence, end all bullets with a full stop. Don't end a bullet with a semicolon (;).
* If all bullets are phrases, or fragments, use no end punctuation.
* **Use Blank Lines** - make sure there is one blank line above and below the list.
#### Numbered List
@@ -116,16 +242,42 @@ If the order of items in the list is irrelevant, use [bullet points](#bullet-poi
2. **Be logical** - the items in the list should follow a logical flow, which guides the reader though the content in a manner that makes sense.
3. **Keep the structure simple** - if your list is getting a bit complex in structure or stretches over several pages, consider breaking it up into a series of sub-sections.
4. **Punctuate consistently** - each item in the list should end with a full stop, unless the item contains [bullet points](#bullet-points).
5. **Use Blank Lines** - make sure there is one blank line above and below the numbered list.
### Code Snippets
###### Example lists
Code snippets provide invaluable 'how to' examples to the reader: often, they are copied directly into a Developer's code.
The bullet points used throughout this page provide examples of the style to be used.
Remember that a snippet is 'a small part or piece of a thing' so keep your snippet short as short as possible and relevant to the section in which it is located.
:::note
Sometimes, it might not be possible to use an emphasized phrase (the part that is in bold) for each bullet. In such cases, try to apply the other bullet point guidelines to your list.
:::
### Markdown Features
### Tabs
For tips and guidelines on formatting Markdown features, see [Formatting Tips](documentation-formatting.mdx).
Since Flipper supports multiple platforms, you may need to provide information that is specific to each platform. The Tab tool provides an excellent way of this information via use of the `CodeLanguageTabs` component.
Tabs provide your reader with an easy method of switching from one platform (or process) to another without having to scroll up and down the page.
#### Markdown code
For an example of using Markdown for tabs, see [Markdown Formatting](documentation-formatting.mdx#tabs)
### Videos
Videos are an effective method of presenting a lot of information to the reader. However, just like [images](#images), the use of videos must be accompanied by knowledge of how to use them effectively. Following are guidelines for the use of video in your documentation:
* **Watch the video** - before you use the video in your documentation, watch it to check that its good quality, relevant to the section in which it's located, and provides sufficient information.
* **Keep the content concise**:
* The content of the video should be limited to the specific purpose for which it is being used.
* For example, if a video is being used to illustrate configuration of a component, it should contain just that process.
* **Refer to the video** - mention the video within the section in which it's being used.
* **State the length of the video**:
* If the length of the video is not shown in the video object, state it in the text.
* For example, "*The following 11-second video demonstrates the slightly different 'Hg: Show Head Changes' command*".
:::tip
When deciding to use a video, keep in mind that it takes much more time to produce a video than to change some text. A small change to a UI or a process is relatively easy to change in text. The same change in a video may mean it needs to be replaced or removed, which, ultimately, involves much more work.
:::
## Resources

2
docs/internals/index.mdx
View File

@@ -17,7 +17,7 @@ This part of the site is for those interested in **how** Flipper works 'under th
<FbInternalOnly>
In addition, the section contains a wide range of internal-only (see 'Under the Hood -> 'Internal') topics, such as:
In addition, 'Under the Hood' contains a wide range of internal-only topics (see the NavBar's 'Internal'), such as:
* [Data Pipelines](../fb/data-pipelines.mdx) - information on Deep Dive, Flipper Analytics, Scribe, Error Logging, plus a series of links relating to architecture, Static Docs, and code Pointers.
* [Launcher](../fb/hackin-on-launcher.mdx) - details of hacking on Launcher and the LauncherConfig.