From 5b70a7d03e93cd6e64dd9fa5ac1524e19db83d3b Mon Sep 17 00:00:00 2001 From: Jim Winstead Date: Tue, 22 Oct 2024 11:41:57 -0700 Subject: [PATCH] Intro to style guidelines, add section about --- docs/style.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/style.md b/docs/style.md index c4bbbf801..f620946b7 100644 --- a/docs/style.md +++ b/docs/style.md @@ -1,5 +1,13 @@ # Style guidelines +The style for the PHP manual has evolved over the years, and this tries +to capture the current guidelines. Existing documentation may not closely +adhere to these, but new additions and substantial changes should. + +When updating existing documentation, it is okay to not update +conflicts with these style guidelines if it would cause too much work +for translators. + ## Technical requirements - All files **must** be encoded using UTF-8 (without BOM) - Use only Unix line endings (`\n`) @@ -24,6 +32,14 @@ a period. Sentences need not have two spaces between them. Commas and apostrophes should be used appropriately. +## Markup + +### Use `` sparingly + +Use `` in markup (similar to HTML's `

`) in favor of `` +(similar to HTML's `

`) when there are no block elements (such as +`` or `` in the paragraph. + ## Personalization The PHP Manual is a technical document, and should be written so. The use of "you" is rampant in the manual, and presents an unprofessional image. The only exceptions to the personalization rule are: the PHP Tutorial and FAQs.