diff --git a/docs/development/contribution-documentation/README.md b/docs/development/contribution-documentation/README.md index 1ce1902793f6..18805882c204 100644 --- a/docs/development/contribution-documentation/README.md +++ b/docs/development/contribution-documentation/README.md @@ -23,7 +23,7 @@ This documentation evolves continuously with new features and improvements to ac ## Where to find the OpenProject documentation? -The documentation for OpenProject is published on https://www.openproject.org/docs/. You can also access the documentation from your OpenProject application under user guides and API documentation below the question mark at the top right in the header menu. +The documentation for OpenProject is published [here](https://www.openproject.org/docs/). You can also access the documentation from your OpenProject application under user guides and API documentation below the question mark at the top right in the header menu. diff --git a/docs/development/contribution-documentation/documentation-process/README.md b/docs/development/contribution-documentation/documentation-process/README.md index 202fc0b7e1ad..bf8f3aaba74b 100644 --- a/docs/development/contribution-documentation/documentation-process/README.md +++ b/docs/development/contribution-documentation/documentation-process/README.md @@ -20,27 +20,15 @@ Please note that you find the [OpenProject repository on GitHub](https://github If you would like to contribute changes to the OpenProject documentation, please follow these steps: 1. [Fork the OpenProject repository](https://www.openproject.org/docs/development/git-workflow/#fork-openproject) and create a local development branch. Include documentation in your branch name. - 2. Create your changes in the documentation. It can be found in the folder [docs](https://github.com/opf/openproject/tree/dev/docs). You can work directly in the GitHub markdown files or use e.g. GitHub desktop and a markdown editor like Typora. - If you are not only changing something in an existing documentation page but are adding a new page, please make sure to add metadata. To provide additional directives and useful information, we add metadata to the beginning of each documentation page. This will give you guidance on what information to provide in the metadata: - -- Sidebar navigation: You do not have to add anything here. Leave it blank. - -- Title: Site title that will appear in the menu. - -- Priority: You assign a number to your page to indicate in what order it will appear. The higher up you want the section to appear in the menu, the higher the number you assign (any number between 1 and 999). I.e. the section that is appearing first gets the highest number (e.g. 999). - -- Description: description of the content of the page that you are creating. Best is to also include the title name. - -- Robots: always add “index, follow” here. - -- Keywords: use key words to describe the content of the page, minimum 2. - - - -3. [Create a pull request](https://www.openproject.org/docs/development/git-workflow/#create-a-pull-request) on our repository. Make sure you name it accordingly and also include documentation in the name. - + - Sidebar navigation: You do not have to add anything here. Leave it blank. + - Title: Site title that will appear in the menu. + - Priority: You assign a number to your page to indicate in what order it will appear. The higher up you want the section to appear in the menu, the higher the number you assign (any number between 1 and 999). I.e. the section that is appearing first gets the highest number (e.g. 999). + - Description: description of the content of the page that you are creating. Best is to also include the title name. + - Robots: always add “index, follow” here. + - Keywords: use key words to describe the content of the page, minimum two. +3. [Create a pull request](https://www.openproject.org/docs/development/git-workflow/#create-a-pull-request) on our repository. Make sure you name it accordingly and also include **documentation** in the name. 4. We will evaluate your pull request and changes before we merge it. If the author or reviewer has any questions, they can use the comments in the pull request. diff --git a/docs/development/contribution-documentation/documentation-style-guide/README.md b/docs/development/contribution-documentation/documentation-style-guide/README.md index 92b1ef82cdb9..d251a14b8155 100644 --- a/docs/development/contribution-documentation/documentation-style-guide/README.md +++ b/docs/development/contribution-documentation/documentation-style-guide/README.md @@ -79,7 +79,7 @@ Do not include the same information in multiple places. Instead, link through to ## References across the documentation - When mentioning other OpenProject modules or features, link to their respective documentation, at least on first mention. -- Please see in [links](../#links) how to use links within the documentation. +- Please see in [links](/#links) how to use links within the documentation. - When making reference to third-party products or technologies, link out to their external sites, documentation and resources. @@ -103,7 +103,7 @@ The OpenProject documentation should be as clear and easy to understand as possi ## Capitalization -### Headings +### Headings Use sentences that describe the content and capitalize the first letter in the sentence. For example: @@ -113,7 +113,7 @@ Use sentences that describe the content and capitalize the first letter in the s -### UI text +### UI text When referring to specific user interface text, like a button label or menu item, use the name as in the application and start the word with a capital letter. Moreover, please make it bold. Example: **Start free trial** button. @@ -193,7 +193,7 @@ Please do not use any contractions like don’t or isn’t. ## Copy -### Punctuation +### Punctuation Follow these guidelines for punctuation: @@ -213,7 +213,7 @@ Use only standard spaces between words so that the search engine can find indivi -## Lists +## Lists Always start list items with a capital letter. @@ -255,8 +255,8 @@ Example for an unordered list: - Do not add commas (`,`) or semicolons (`;`) to the ends of list items. - Separate list items from explanatory text with a colon (`:`). For example: - - Feature 1: very attractive new feature - - Feature 2: description of an additional feature + - Feature 1: very attractive new feature + - Feature 2: description of an additional feature @@ -272,15 +272,11 @@ To keep tables accessible and scannable, tables should not have any empty cells. To help tables be easier to maintain, consider adding additional spaces to the column widths to make them consistent. For example: -| Feature | Description | - -| --------------------- | :----------------------------------------------------------------------------------- | - -| Great feature | Enhances collaboration between marketing and sales | +| **Feature** | **Description** | +| ---------------------------------------------------------- | ------------------------------------------------------------ | +| Great feature | Enhances collaboration between marketing and sales | +| Best feature | Use it to synchronize your example table with OpenProject | -| Best feature | Use it to synchronize your example table with OpenProject | - - ## Headings @@ -298,7 +294,7 @@ To help tables be easier to maintain, consider adding additional spaces to the c - Make your subheading titles clear, descriptive, and complete to help users find the right example. -- See [Capitalization](../#capitalization) for guidelines on capitalizing headings. +- See [Capitalization](/#capitalization) for guidelines on capitalizing headings.