Style guide

this page is the writing style guide for flipper one documentation it exists to keep tone, formatting, and terminology consistent across every page contributors write or edit ℹ️ how to use this guide before opening a pull request in the docs repository, skim this page to make sure your contribution follows our style guide if you use an ai assistant to write or edit, point it to this guide so it matches our tone and formatting tone of voice three principles guide our voice clear & accessible friendly open & honest clear & accessible keep it simple use plain language avoid jargon unless you define it choose the most common, easy to read words show, don’t tell use visuals such as diagrams, screenshots, and short videos wherever they help be empathetic think like a reader what do they want to know? how would they search for it? focus on the user build the narrative around the reader’s benefit, not around us instead of listing features, explain what those features let the user do be brief say it clearly and keep it short can the sentence lose words without losing meaning? ✅ put pasta in a pan ❌ take a deep metal cooking vessel, open a pack of pasta… show interaction communication in images clear and short instructions communication in videos friendly write as if you’re speaking directly to a reader be polite and human, without being overly familiar this means keeping a dialogue with the community healthy, non cringe communication compare “prohibited!!” with “please do not touch the flowers ” open & honest we follow open source values honest, transparent, human communication we don’t hide problems we admit mistakes, share experience, and let readers see what happens behind the scenes language we use american english minus americanisms we aim for the simplest possible language (basic / plain english) that an a2–b1 english speaker can easily understand ℹ️ general rules always use an automatic spell checker (grammarly, vs code spell check extension, or similar) when choosing words, terms, or phrases, prefer the most common and simplest options where to check spelling merriam webster https //www merriam webster com/ for general vocabulary google style guide — word list https //developers google com/style/word list for technical / it vocabulary structure and layout preparing text for publication is closely tied to layout and design visual hierarchy the reader should immediately see what is primary and what is secondary create a visual hierarchy from large to small elements using heading levels and text formatting ℹ️ the larger, the more important visual hierarchy ‎ captions for pictures and videos captions are typically required exceptions the image already contains a title or text the illustration’s meaning is obvious without one for videos, start the caption with \[video] ℹ️ no period at the end of a caption ‎ avoid typographic orphans avoid leaving a single word alone on the last line of a paragraph or heading, especially for important elements like page titles or call to action lines ‎ avoid repeating the same word on neighboring lines rewrite to reduce visual monotony when the same word lands on two adjacent lines formatting heading and title format element case page title sentence case headings in the body of a page sentence case ‎ bold bold is used for emphasis, inline headings, and to attract attention use it sparingly when everything is bold, nothing is ⚠️ avoid mixing bold with links within the same paragraph it makes the text look cluttered ‎ descriptive and meaningful link text use link text that accurately describes the destination nobody likes links with vague targets ❌ bad 👍 better 💎 perfect click here see source code see source code on github ‎ use the entire logical phrase for link text ✅ read about the mjs scripting engine https //example com ❌ read about the mjs https //example com scripting engine do not include the article (unless it’s part of a proper name) or any punctuation after the link text ‎ urls as link text urls can be used as link text when the url itself is informative in that case remove http // and www from the beginning place urls only at the end of a paragraph, with no text following do not add a period after the url make sure the url stays short and readable ✅ reader friendly url ❌ long and unreadable url wikipedia org/wiki/flipper zero https //ru wikipedia org/wiki/%d0%9e%d0%ba%d0%b8%d0%bd%d0%b0%d0%b2%d0%b0 ‎ emojis emojis are welcome as they add helpful visual anchors and make content easier to scan some readers associate emojis with ai generated text, but that’s not a reason to avoid them use emojis with intent use an emoji when it adds a clear visual anchor, not as decoration keep them consistent reuse the same emoji for the same meaning across a page grammar and syntax keep sentences short, simple, and concise avoid complex grammar that may cause confusion ‎ articles with flipper devices the same rules apply to flipper zero and flipper one without an article the device as a platform or tech solution; emphasis on the idea example flipper one is built around a rockchip rk3576 a flipper zero / a flipper one one non specific device the flipper zero / the flipper one a specific device, or the concept as a category (compare the apple is a healthy fruit ) ‎ contractions mostly use the contracted form (don’t, can’t, we’ll) as it makes text more natural and concise but when you want to emphasize something, switch to the full form use full forms for emphasis full form what it emphasizes we will contact you a definite promise that we’ll contact you for sure please do not unplug the device a firm instruction not to do something we have added a new feature this is the latest news words and spelling general rules always use an automatic spell checker recommended tools grammarly, the vs code spell check extension, or any equivalent where to check spelling merriam webster https //www merriam webster com/ for general vocabulary google style guide — word list https //developers google com/style/word list for technical / it vocabulary ‎ terminology use consistent terms that are actually used in the industry readers scan rather than read every word, so a term that shifts mid page (for example, switching between “firmware update” and “device update”) makes content harder to follow ‎ abbreviations use abbreviations when they improve readability common slang abbreviations like tl;dr are fine avoid latin abbreviations like i e or e g instead, write that is or for example spelling out abbreviations if an abbreviation might be unfamiliar, spell it out the first time, followed by the abbreviation in parentheses subsequent mentions can use the abbreviation alone examples border gateway protocol (bgp) elliptic curve cryptography (ecc) if the first mention is in a heading, you can spell it out in the first paragraph after the heading plurals abbreviations form plurals like regular words apis , sdks , ides ‎ hyphenated words use a hyphen ( ) to prevent misreading or to build compound words when multiple options exist, prefer the unhyphenated form ✅ firmware update ❌ firmware update always hyphenate in these cases self or cross self managing , cross region before a capitalized noun or a number non google , post 2000 to avoid misreading de energize , intra index , re mark , re sign when the term already contains hyphens or spaces un google like , non twentieth century for consistency within a document pre processing , post processing punctuation and typography period a period normally ends a paragraph omit the period in captions docid\ dkc9huqqrtlc9mykbl4ng and lists docid\ dkc9huqqrtlc9mykbl4ng (see below) ‎ comma introductory comma use a comma after introductory words, phrases, or clauses at the start of a sentence oxford (serial) comma use a comma before and or or when listing three or more items flipper zero can emulate access badges, read radio signals , and write data to nfc tags space for exceptions sometimes a comma clutters the layout or sounds pedantic in those cases, feel free to leave it out ‎ lists as a rule, don’t put punctuation at the end of list items this style looks most natural in english and matches our tone ℹ️ exception if the list contains long or multiple sentences, use a period at the end of every item ‎ dash use an em dash ( — ) for parenthetical breaks and asides, with spaces on both sides use a hyphen ( ) for ranges and compound words instead avoid en dashes ( – ) ✅ the module is powered by the first chip designed by raspberry pi — the rp2040 microcontroller ❌ the module is powered by the first chip designed by raspberry pi the rp2040 microcontroller even though we use em dashes, place them sparingly, as extensive use is often considered a sign of ai generated text ‎ quotation marks and apostrophes in documentation, use typographic (“curly”) quotation marks and apostrophes ‘…’ and “…” mixing straight and curly marks in the same sentence (for example, doesn’t with a curly apostrophe and you'll with a straight one) looks unprofessional it’s a common mistake, so watch for it ℹ️ on macos, you can have curly quotes inserted automatically system settings → keyboard → text input → edit , then enable use smart quotes and dashes numbers spell out numbers as words up to ten , then switch to digits ℹ️ exceptions the reader needs to scan the number quickly the number is followed by a unit of measurement ‎ ranges of numbers use a hyphen between two numbers avoid using en or em dashes ✅ 2012 2016 ‎ suspended hyphens when two or more hyphenated compounds modify the same word, drop the repeated word from the earlier compounds and keep the hanging hyphens ✅ you can set up the system to scan for new files at one , two , or three hour intervals ‎ currency currency symbols are always written before the number for us dollars, use the $ sign with no space between the sign and the number ✅ the price is $0 006653 per vcpu hour $10,000 in fees is out of reach for many developers ‎ commas and decimal points use commas and decimal points according to standard american number formatting in numbers of four or more digits, use commas to group threes (counting leftward from the decimal point) use a period for the decimal point ✅ ❌ the limit is 1,532,784 bytes per day the limit is 1532784 bytes per day the api supports up to 2,000 vertices the api supports up to 2000 vertices $0 031611 /vcpu hour $0,031611/vcpu hour ‎ dimensions use a lowercase x between numerals, with no space between the numerals and the x ✅ 192x192 ❌ 192 x 192 ‎ dates write out months whenever possible separate the month from the year with a comma because it's easier to read and the most commonly used format ✅ august 8, 2024 the abbreviated form aug 8, 2024 is also fine if using all numerals, the most universally understood format is dd mm yyyy you can use periods or forward slashes as separators ( dd mm yyyy or dd/mm/yyyy ) stay consistent within a single document ℹ️ avoid all numeric forms like 1/2/2011 as they can be read as either january 2 or february 1, depending on the reader’s region units of measurement spacing put a space between the number and the unit, and use a non breaking space so the value never wraps onto two lines ✅ 64 gb, 25 mm, 300 k exceptions use no space for currency, percentages, and angles ✅ $10, 65%, 180° for temperatures, put a space before the degree symbol but none between the symbol and the scale ✅ 50 °c ❌ 50°c, 50° c ‎ ranges repeat the unit for each number and use to between them instead of a hyphen ✅ 40 °c to 85 °c ❌ 40 85 °c ‎ multiplied units when the parts of a unit are multiplied together, hyphenate them ✅ 5 vcpu hours, 40 person hours ‎ rates use per instead of a division slash ( / ) when space allows use abbreviated rate units like gbps or mbps only when they’re well established ‎ thousands use a lowercase k with no space, and add a clarifying noun so it isn’t mistaken for kilobytes ✅ 55k download operations ‎ decimal vs binary units keep decimal and binary units distinct kb / mb / gb are decimal, while kib / mib / gib are binary don’t write mb when you mean mib , or gb when you mean gib