From 890abbbf88729bf54c08d93934a62d034e40dfb1 Mon Sep 17 00:00:00 2001 From: Matthias Schrumpf Date: Wed, 5 Mar 2025 14:37:28 +0100 Subject: [PATCH 1/3] add meta-documentation --- docs/guides/meta/index.md | 5 + docs/guides/meta/mkdocs.md | 272 +++++++++++++++++++++++++++++++++++++ 2 files changed, 277 insertions(+) create mode 100644 docs/guides/meta/index.md create mode 100644 docs/guides/meta/mkdocs.md diff --git a/docs/guides/meta/index.md b/docs/guides/meta/index.md new file mode 100644 index 00000000..4fc7111d --- /dev/null +++ b/docs/guides/meta/index.md @@ -0,0 +1,5 @@ +# Meta documentation + +This section of the documentation explains how the documentation itself works, how it was written, and how to contribute to it. +This is directed at both coworkers, and at external contributors. +It also serves as a reminder for the people writing the docs themselves how we do certain things, and why we decided to do them that way. \ No newline at end of file diff --git a/docs/guides/meta/mkdocs.md b/docs/guides/meta/mkdocs.md new file mode 100644 index 00000000..7e01855f --- /dev/null +++ b/docs/guides/meta/mkdocs.md @@ -0,0 +1,272 @@ +# Writing for MkDocs + +This article describes the more technical side of technical writing for pretix. +It explains how to structure certain types of information, and what syntax to use to do it properly. + +!!! Warning + As of now, the text below has been machine-translated, so take it with a grain of salt. + +## Image Descriptions + +You can find basic information on how to write a good image description at [Axess Lab](https://axesslab.com/alt-texts/). +This is how you include an image description in markdown: +``` +![Media description for visually impaired users or users with an unreliable internet connection](../path/to/file.png "Image Title") +``` + +Example: + +``` +![Screenshot of page titled "Create new Event–Step 2", showing options for choosing name, short form, date, location, and geo coordinates for the event. Not pictured: currency, sales tax rate, time zone, start and end date of presale.](../assets/screens/event/create-event2.png "Create new event step 2 screenshot") +``` + +For creating screenshots, see [this guide](https://ramiio.atlassian.net/wiki/spaces/DOCS/pages/1149599746). + +## Buttons + +Mark all buttons that you want the user to click the following way: + +``` +:btn:Button Label: +``` + +If a button includes an icon, include the icon before the button label: + +``` +:btn-icon:icon-name:Button Label: +``` + +Example: + +``` +The :btn-icon:fa3-upload: Import vouchers: button lets you upload such a list after saving it from a different event. +``` + +>The :btn-icon:fa3-upload: Import vouchers: button lets you upload such a list after saving it from a different event. + + +Do **not** mark buttons this way if you are not telling the user to click them. +Put them in quotation marks instead. + +## Navigation Paths + +Navigation paths start either from a placeholder ("Your Event") or from the dashboard. +For consistency and accessibility reasons, use this formatting for all navigation paths. +You can insert icons at any point in the path. +Close it with `:`. +Use ` → ` (AltGr + i) between each step. +Do not forget the spaces around the arrow. +Paths starting from the dashboard automatically begin with an arrow pointing to the first element. + +Examples: + +``` +:navpath:Your Organizer → Layer1 → Layer2: +:rootnavpath:Layer1 → Layer2: +:navpath:Your Event → :fa3-ticket:Layer1 → Layer2: +``` + +## Input Fields + +Use quotation marks and the label in the exact spelling as it occurs in the UI for interactive elements such as text input fields and drop-down menus. +Refer to them explicitly as a "field" or as a "menu". + +Example: + +``` +In the "Check-in text" field, provide instructions for the person operating the check-in at your event. +``` + +Refer to a checkbox as "the checkbox next to [Label]". +If the instructions already contain the words "check" or "uncheck", refer to them as "box". + +Example: + +``` +Check the box next to "requires special attention". +``` + +There is currently no standard formatting for radio buttons or other controls. + +## Admonitions + +If you want to inform the reader about legal, technical, or irreversible actions, use colored text boxes. +The color is based on ISO standards: + + - **Blue** for notes + - **Yellow** for warnings + +Use three exclamation marks and a space `!!! ` followed by the box type. +If you do not specify a title, the title of the box will default to the type ("Note" or "Warning"). +Indent the text of the warning with four spaces. +To continue with normal text, insert an empty line and remove the indentation. + +Example: + +``` +!!! Note + Reading note boxes is useful. +``` + +If a note or warning box is used in multiple articles, place it in the `include` directory. +If it is used in only one article, you do not have to do that. +Just write the warning right into the article. + +To include a reusable text block, use the following formatting: + +``` +{% include "note-translations.md" %} +``` + +MkDocs supports several more types of admonitions. +The pretix documentation currently only uses notes and warnings. +If you think it is necessary to use any other type of admonition, talk to the team before you do so. + +## Icons + +As of 03/2025, pretix predominantly uses Font Awesome 3 icons, as well as some custom icons. +These icons can be found in the repo at `/overrides/.icons/`. +In order to insert an icon into the text, use `:fa3-iconname:`, where `iconname` is the filename of the icon minus the file type extension. +For example, use `:fa3-transgender-alt:` for the icon :fa3-transgender-alt: and use `:i-seat:` for :i-seat:. + +## Links and Cross-References + +Do **not** insert external or internal links without context. +Make them as informative as possible in their descriptive text (i.e. what is visible to readers in the text and looks like a hyperlink). +Make them large enough so that the reader can click them without great effort. +Single words such as "here" and "next" are not suitable as link text. + +Screen readers sometimes read out contextless lists of links. +Hearing the link text "here" five times in a row is not very informative. +Even without a screen reader, it helpful for the reader if they have a general idea what is behind the link. + +Internal and external links are preceded by different symbols in the documentation visible to readers to make it easier to distinguish between them. +You do not have to specify this because it works automatically. +The formatting for both types of links is "link text in square brackets, URL/path in round brackets". +Insert cross-references to a subheading within another (or the same) article work as follows: + +``` +[monitoring incoming payments](../topics/payment/bank-transfer.md#monitoring-incoming-payments) +``` + +If you want to link to the entire article, omit the # symbol and the parts after it. +You can also omit parts of the file path that are identical to the path of the current file. +Examples: + +``` +Our organizer's profile and all the events we are going to create will be found at [https://pretix.eu/tut/](https://pretix.eu/tut/) from now on. + + In this tutorial, we will be: + + - creating a [personal and organizer account](getting-started.md#creating-an-account) + - setting up our [organizer account](organizer-account.md) + - creating our [event](event.md) +``` + +If you link an article that is not yet available (e.g. due to an open pull request), Github will throw a warning. +To avoid this, put a space between square and round brackets and leave a corresponding comment starting with "TK". + +``` +TK fix link after merge +``` + +## Placeholders + +Use `:placeholder: ... :` to mark placeholders outside of navigation paths. +These will be displayed the same way as placeholders *within* navigation paths. +This does not work in combination with button or icons formatting +Example: + +``` +A shop created with pretix Hosted will by default be located at https://pretix.eu/:placeholder:OrganizerShortForm:/:placeholder:EventShortForm:/. +``` +>A shop created with pretix Hosted will by default be located at https://pretix.eu/:placeholder:OrganizerShortForm:/:placeholder:EventShortForm:/. + + +## Line Breaks + +Put a line break after each single sentence. +If each sentence is not in a single line in the .md file, then reviewing the article through GitHub becomes very messy and difficult. + +You can use the following command to automatically move every sentence in a text file (Markdown) to a separate line. +This command is as follows: + +``` +sed 's|\. |. \n|g' < input.md > output.md +``` + +!!! Warning + The name of the output file must be different from the name of the input file, otherwise the command will create an empty file. + +This command searches for occurrences of ". " (i.e. dot followed by space) and replaces them with dot followed by space followed by newline. +This also adds line breaks after abbreviations such as "e.g.". +It can also create double empty lines. +Edit the output file and remove unnecessary linebreaks manually. +Markdown renders simple line breaks as spaces. +There is no need to remove the space at the end of the sentence. +Markdown renders empty lines as line breaks. +Make sure there is an empty line separating every pair of paragraphs. + +If want to add additional line breaks to the output text on the website, put at least two spaces at the end of the line of markdown code. +You can insert additional empty lines using `
`. +Insert additional empty lines wherever an image is located between two paragraphs, but concerns the content of only one of the paragraphs. +Insert `
` between the image and the topically **separate** paragraph. + +## English Punctuation + +English and German have different punctuation rules. +This is an overview over commonly used special characters. + +For money, put currency symbol at the beginning, do not separate it with a space, use the comma for thousands, and use the period for decimals. + +`€1,899.99` + +For percentages, do not use a space between the number and the symbol. + +`19%` + +For quotation marks, use `"` (U+0022 QUOTATION MARK). +Double-check that you have the correct quotation mark when copying text from Confluence, word editors, or other websites. +They will sometimes replace the quotation mark above with a different symbol such as `”`. +This symbol should not occur anywhere in our documentation (except here, as a deterrent example). + +The hyphen and minus are the same symbol: `-`. +The en-dash is a separate symbol, which is currently not used in our documentation: `–` +The em-dash is yet another separate symbol: `—` (U+2014 EM DASH). +Use the em-dash without spaces before or after it. + +## Articles Specific to Germany + +Some articles in our documentary are only relevant for the German-speaking world, for instance because they concern organizations that only exist in Germany. +Although the rest of our documentation is published in English first, it makes sense to write these articles in German. + +Because of the way MkDocs organizes the navigation on the website, you have to handle these articles in a special way. +Put the main text of the article in the `include` directory. +Do not put a level 1 heading or title in the file. +Then, create a file with the following content in the `docs` directory where the article actually belongs: Heading, note on language and include command for the main text. +Example: + +``` +# KulturPass + +!!! Note + Since the KulturPass is specific to event organizers within Germany, the following page is also only provided in German. + Should you require assistance with the KulturPass and do not speak this language, please feel free to reach out to . + +{% include "kulturpass.md" %} +``` + +Then, create a file with the extension .de.md in the same directory, which only contains the title and the include command. +Do not put the hint regarding the language into the German docs file. + +## Indicating pretix Editions + +Mark sections that are specific to certain pretix editions the following way: + +``` + + + +``` + +You can use the same formatting for specific version updates. \ No newline at end of file From 3ab1912d48130f9f8604a3d17f5274b8c33fe527 Mon Sep 17 00:00:00 2001 From: Matthias Schrumpf Date: Thu, 10 Apr 2025 17:04:21 +0200 Subject: [PATCH 2/3] index.md: add instructions on what to do and what not to do when contributing to pretix-docs --- docs/guides/meta/index.md | 112 +++++++++++++++++++++++++++++++++++++- 1 file changed, 111 insertions(+), 1 deletion(-) diff --git a/docs/guides/meta/index.md b/docs/guides/meta/index.md index 4fc7111d..e0415df7 100644 --- a/docs/guides/meta/index.md +++ b/docs/guides/meta/index.md @@ -2,4 +2,114 @@ This section of the documentation explains how the documentation itself works, how it was written, and how to contribute to it. This is directed at both coworkers, and at external contributors. -It also serves as a reminder for the people writing the docs themselves how we do certain things, and why we decided to do them that way. \ No newline at end of file +It also serves as a reminder for the people writing the docs themselves how we do certain things, and why we decided to do them that way. + +## How to write documentation for pretix + +When writing documentation for pretix, do your best to stick to the [maxims of conversation](https://en.wikipedia.org/wiki/Cooperative_principle#Grice's_maxims) as postulated by linguist Paul Grice. +These maxims, when applied to the task of documenting pretix, entail the following: + + 1. Maxim of quantity: be informative. + + Give complete instructions. + Do not skip any necessary steps. + For instance, if it is necessary to save the settings before they can take effect, then clicking the "Save" button is an essential step. + Omit any information that is not needed for the task at hand. + + 2. Maxim of quality: be truthful. + + Check and double-check that your instructions actually work when using pretix. + Do not include any factually inaccurate information. + Do not include any uncertain information. + Missing information is still better than wrong information. + + 3. Maxim of relation: be relevant. + + Explain how to use pretix. + Explain how pretix works. + Do not explain anything else. + + 4. Maximum of manner: be clear. + + Write clear, simple, and straightforward as possible. + Keep sentences short. + Avoid obscure and complex expressions. + Provide the steps in the exact order that the user needs to follow. + Provide navigation instructions in order from largest (most general) to smallest (most specific). + +## What NOT to do when writing documentation for pretix + +What follows is an incomplete lists of things you might be tempted to do when contributing, but which do not fit into the concept of the pretix documentation. +This section will help you understand why these things are not a good idea. + +### Do not use Artificial Intelligence (AI) + +Do not use so-called artificial intelligence (AI), for instance Large Language Models (LLMs) such as ChatGPT. +LLMs can generate text that, on the surface, looks professional and accurate. +LLMs cannot do research. +LLMs cannot interact with pretix like a human user can. +The texts that LLMs produce cannot be guaranteed to be factually accurate. +They will often contain false information. + +As it is stated under the maxim of quality, missing information is better than wrong information. +You can improve the pretix documentation by researching the information and putting it into words yourself. +You cannot improve it by prompting an LLM to do it. + +### Do not contribute machine-translated text + +Machine translators such as DeepL or Google Translate can be of great help when translating the pretix documentation into another language. +However, you cannot rely on machine translation alone to provide a good translation. +Cross-reference the UI in the target language. +Change all texts, labels, buttons and other UI elements mentioned in the translated text to match the ones on the website. +Edit the terminology in the target language to be accurate, consistent, and distinct. +Correct grammar, spelling and punctuation in the target language so that they follow established standards. + +### Do not use empty phrases + +Avoid unnecessary fluff such as: + + - "Make sure that" + - "Please" + - "Note that" + - "It is, however, necessary to note that" + - "important" + - "critical" + +### Do not overuse notes and warnings + +Before adding an admonition (a note or a warning), ask yourself if the information is necessary for following the instructions in the main text. +If it is, then it does not belong in an admonition. + +Do not place two or more admonitions directly after one another. + +Do not use admonitions other than notes or warnings. +If you think that that is necessary, talk to the docs team first. + +## Best Practices: What to do when writing documentation for pretix + +What follows is an incomplete list of Best Practices, i.e., things you **should** do when contributing to this documentation. + +### Read the documentation + +The more familiar you are with the documentation, the better prepared you are for contributing to it. +In addition to the webpages themselves, also take a look at the source code. +Try to make your contribution look like the pages that are already there. + +### Contact the team + +Talk to the docs team. +Create an issue on the GitHub page for [pretix-docs](https://github.com/pretix/pretix-docs/issues) or send an email to [pretix support](mailto:support@pretix.eu). +The support team will forward your mail to the docs team. + +The docs team will answer any questions you might have regarding your contribution. +They will be able to tell you whether it is relevant; where it fits into the established structure of the documentation; whether there are any internal resources on the subject; and so on. + +You are helping the docs team a great deal by contacting them before submitting a pull request. +Reviewing a PR, fixing the formatting and discussing how it fits into the concept of the documentation is more work than discussing a few open questions ahead of time. + +### Follow the instructions on writing for MkDocs + +Consult the article on [writing for MkDocs](mkdocs.md). +This documentation is fairly formalized. +Each type of information has its own specific formatting. +The linked article explains how to use Markdown and MkDocs to format each type of information. \ No newline at end of file From ac8accbeb34fd27c000acf57aec6ffd65427408a Mon Sep 17 00:00:00 2001 From: Matthias Schrumpf Date: Wed, 23 Apr 2025 15:19:10 +0200 Subject: [PATCH 3/3] expand ## What NOT to do when writing documentation for pretix and ## Best Practices --- docs/guides/meta/index.md | 56 +++++++++++++++++++++++++++++++++++---- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/docs/guides/meta/index.md b/docs/guides/meta/index.md index e0415df7..c47b1dde 100644 --- a/docs/guides/meta/index.md +++ b/docs/guides/meta/index.md @@ -27,7 +27,7 @@ These maxims, when applied to the task of documenting pretix, entail the followi Explain how to use pretix. Explain how pretix works. - Do not explain anything else. + Only explain processes external to pretix if they are necessary for a feature of pretix to work. 4. Maximum of manner: be clear. @@ -46,8 +46,8 @@ This section will help you understand why these things are not a good idea. Do not use so-called artificial intelligence (AI), for instance Large Language Models (LLMs) such as ChatGPT. LLMs can generate text that, on the surface, looks professional and accurate. -LLMs cannot do research. -LLMs cannot interact with pretix like a human user can. +But LLMs cannot do research. +They cannot interact with pretix like a human user can. The texts that LLMs produce cannot be guaranteed to be factually accurate. They will often contain false information. @@ -80,11 +80,28 @@ Avoid unnecessary fluff such as: Before adding an admonition (a note or a warning), ask yourself if the information is necessary for following the instructions in the main text. If it is, then it does not belong in an admonition. -Do not place two or more admonitions directly after one another. +Do not place two or more admonitions directly after one another if possible. Do not use admonitions other than notes or warnings. If you think that that is necessary, talk to the docs team first. +### Do not attempt to replace the documentation for third-party software + +Some features of pretix can only be used in conjunction with third-party software. +Examples of this include plugins that interface with a third-party service, particularly payment providers, as well as data exports. +Under the maxim of quantity, it is stated that you should "[g]ive complete instructions" and that you should "not skip any necessary steps". +This would imply that you need to give complete instructions on what steps to take in the third-party software as well. +However, as it is stated under the maxim of relation: +"Only explain processes external to pretix if they are necessary for a feature of pretix to work." + +Third-party software is a moving target. +The pretix team does not have any insight into its development. +This means that whenever a change takes place, it can take months or even years until that change is noticed and can be reflected by an update to the documentation. + +As a result of this, it makes more sense to describe the necessary steps in the third-party software not click-by-click, but in broad strokes. +Describe how to cross-authenticate pretix and the third-party software, what codes and URLs to copy back and forth, etc. +But for more in-depth use of the other software, try to find a corresponding page in their documentation and link to that. + ## Best Practices: What to do when writing documentation for pretix What follows is an incomplete list of Best Practices, i.e., things you **should** do when contributing to this documentation. @@ -112,4 +129,33 @@ Reviewing a PR, fixing the formatting and discussing how it fits into the concep Consult the article on [writing for MkDocs](mkdocs.md). This documentation is fairly formalized. Each type of information has its own specific formatting. -The linked article explains how to use Markdown and MkDocs to format each type of information. \ No newline at end of file +The linked article explains how to use Markdown and MkDocs to format each type of information. + +### Try it yourself + +The best way to understand how to use a feature of pretix is trying to use that feature yourself. +If you want to document, say, how to use the seating plan editor, log into your pretix account and use the feature editor yourself. +Note every step you have to take and every issue you encounter along the way. +This brings you fairly close to a complete step-by-step guide for the feature. + +### Add cross-references + +One aim of this documentation is to facilitate the search for relevant information for the reader. +The first time you mention a concept or feature in an article, link to the relevant article. +Make these links informative. +For example, after mentioning gift cards in an article, insert a cross-reference such as the following: + +``` +For more information, see the article on [gift cards](../gift-cards.md). +``` + +If you are contributing a new article, check the existing documentation for mentions of the subject of your article and insert references to your article. + +### Link to external documentation + +Insert links to pretix blog posts, Wikipedia, third-party software documentation, legal texts, or high-quality how-to guides on other websites. +The readers of this documentation benefit from curated links to relevant information. +That way, they do not have to search for the missing information themselves and there is a reduced risk of them encountering bad information. + +Strip any and all unnecessary data (such as tracking) from a link before inserting it. +Any links to external websites will have to be checked frequently to make sure that they still point to the desired website. \ No newline at end of file