diff --git a/docs/guides/meta/index.md b/docs/guides/meta/index.md new file mode 100644 index 00000000..c47b1dde --- /dev/null +++ b/docs/guides/meta/index.md @@ -0,0 +1,161 @@ +# 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. + +## 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. + Only explain processes external to pretix if they are necessary for a feature of pretix to work. + + 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. +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. + +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 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. + +### 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. + +### 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 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