Skip to content

Commit

Permalink
Merge pull request #14681 from opf/documentation/fixes
Browse files Browse the repository at this point in the history 
Documentation/fixes
  • Loading branch information
@as-op
as-op committed Jan 31, 2024
2 parents ff2a51f + 2f10800 commit dcfa70e
Show file tree
Hide file tree
Showing 16 changed files with 140 additions and 313 deletions.
109 changes: 34 additions & 75 deletions docs/development/application-architecture/README.md
View file

Large diffs are not rendered by default.

68 changes: 7 additions & 61 deletions docs/development/concepts/secure-coding/README.md
View file

Large diffs are not rendered by default.

81 changes: 1 addition & 80 deletions docs/development/contribution-documentation/documentation-style-guide/README.md
View file
Expand Up @@ -10,14 +10,10 @@ keywords: documentation style guide, style guide, format, style

This document defines the standards for the OpenProject documentation, including grammar, formatting, wording and more.



## Markup language

All OpenProject documentation is written in Markdown. Feel free to either work directly in the Markdown files or to use [GitHub desktop](https://desktop.github.com) with a markdown editor like [Typora](https://typora.io) or others.



## Documentation structure

The OpenProject documentation is divided into the top level folders:
Expand All @@ -32,8 +28,6 @@ Within each folder there is a sub-hierarchy of topics. E.g. in the Getting start

![OpenProject_documentation_menu_left_side_unfolded_sub_topics](OpenProject_documentation_menu.png)



### Folder content

We aim to have a clear hierarchical structure with meaningful URLs like `https://www.openproject.org/docs/getting-started/sign-in-registration/`. With this structure you can identify straight away that this part of the documentation is about the sign in and registration process. At the same time, the website path matches our repository, making it easy to update the documentation.
Expand All @@ -52,8 +46,6 @@ Find an overview of content per folder here:
| [Development](../../../development/) | This guide details how to contribute to the code of the OpenProject application. |
| [API](../../../api/) | This part of the documentation deals with the API specification, what endpoints and functionality are available. |



## Directory and file names

Please respect the following when working with directories and files:
Expand All @@ -80,13 +72,10 @@ Please respect the following when working with directories and files:

If you are unsure where to place a document or a content addition, this should not stop you from authoring and contributing. Use your best judgment, and then add a comment to your pull request.


## No duplication of information

Do not include the same information in multiple places. Instead, link through to the information in the documentation where it is already mentioned so that there is only a single source of truth that needs to be maintained.



## References across the documentation

- When mentioning other OpenProject modules or features, link to their respective documentation, at least on first mention.
Expand All @@ -95,14 +84,10 @@ Do not include the same information in multiple places. Instead, link through to

- When making reference to third-party products or technologies, link out to their external sites, documentation and resources.



## Structure in documents

- Structure content in tables or lists etc. in alphabetical order unless there is a reason to use any other order of importance.



## Documentation language

The OpenProject documentation should be as clear and easy to understand as possible. Avoid unnecessary words.
Expand All @@ -123,14 +108,10 @@ Use sentences that describe the content and capitalize the first letter in the s

`## Start a new trial installation`



### 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.



### Feature names

Feature names are typically capitalized (the first word) and in bold. For example:
Expand All @@ -141,9 +122,6 @@ Feature names are typically capitalized (the first word) and in bold. For exampl
- **News**
- **Wiki**




#### Other terms

Capitalize names of:
Expand All @@ -153,8 +131,6 @@ Capitalize names of:

Follow the capitalization style by the third party which may use non-standard case styles. For example: OpenProject, GitHub.



## Placeholders

### User information
Expand All @@ -167,22 +143,16 @@ You may need to include user information in entries. Do not use real user inform

- Screenshots: When inserting screenshots in the documentation, make sure you are not giving away your identity by using your actual avatar. Rather create a fake user name and avatar.



### URLs

When including sample URLs in the documentation, use example.com when the domain name is generic.



### Tokens

There may be times where a token is needed to demonstrate an API call. It is strongly advised not to use real tokens in documentation even if the probability of a token being exploited is low.

You can use this fake token as example: 12345678910ABCDE



### Commands

You might want to provide a command or configuration that uses specific values.
Expand All @@ -195,14 +165,10 @@ For example:
cp <your_source_directory> <your_destination_directory>
```



## Contractions

Please do not use any contractions like don’t or isn’t.



## Copy

### Punctuation
Expand All @@ -217,20 +183,14 @@ Follow these guidelines for punctuation:

- When a colon is part of a sentence, always use lowercase after the colon.



### Spaces between words

Use only standard spaces between words so that the search engine can find individual search terms.



## Lists

Always start list items with a capital letter.



### Ordered and unordered lists

Only use ordered lists when their items describe a sequence of steps to follow.
Expand All @@ -245,8 +205,6 @@ Follow these steps:

3. And then finish off with something else.



Example for an unordered list:

- Feature 1
Expand All @@ -255,29 +213,21 @@ Example for an unordered list:

- Feature 3



### Markup

- Use dashes (`-`) for unordered lists.



### Punctuation

- 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



## Tables

Tables should be used to describe complex information. Note that in many cases, an unordered list is sufficient to describe a list of items with a single, simple description per item. But, if you have data that is best described by a matrix, tables are the best choice.



### Creation guidelines

To keep tables accessible and scannable, tables should not have any empty cells. If you still remain with a cell without content, please enter N/A (for ‘not applicable’) or none.
Expand All @@ -300,8 +250,6 @@ instead of:
| Best feature | Use it to synchronize your example table with OpenProject |
```



## Headings

- Add only one H1 in each documentation page, by adding # at the beginning of the headline (when using Markdown).
Expand All @@ -320,36 +268,26 @@ instead of:

- See [Capitalization](#capitalization) for guidelines on capitalizing headings.



### Heading titles

Keep heading titles clear and direct. Make every word count. Where possible, use the imperative. Example: Sign in with an existing account (**not** Signing in with an existing account).



### Anchor links

Headings generate anchor links when rendered. ##This is an example generates the anchor #this-is-an-example.
Headings generate anchor links when rendered. `## This is an example` generates the anchor `#this-is-an-example`.

Keep in mind that there are various links to OpenProject documentation pages and anchor links on the internet to take the users to the right spot. Thus, please avoid changing headings.



## Links

Links are important in the documentation. Use links instead of duplicating content to help preserve a single source of truth in the OpenProject documentation.



### Basic link criteria

- Use inline link Markdown markup `[Description](https://example.com)`. It is easier to read, review, and maintain.

- Use meaningful anchor text descriptions. For example, instead of writing something like `Read more about Gantt charts [here](LINK)`, write `Read more about [Gantt charts](LINK)`.



### Links to internal documentation

Internal links are links within the OpenProject website which includes the OpenProject documentation. In these cases, use relative links. I.e. do not use the full URL of the linked page but instead show the current URL's relation to the linked page's URL.
Expand All @@ -359,20 +297,14 @@ To link to internal documentation:
- Use relative links to Markdown files in the same repository.
- Use ../ to navigate to higher-level directories.



### Links to external documentation

When linking to external information, you have to use absolute URLs. Make sure that you are only linking to an authoritative source, i.e. official and credible sources written by the people who created the item or product. These sources are the most likely to be accurate and remain up to date.



## Navigation

When documenting navigation through the OpenProject application, use these terms.



### Menus

Use these terms when referring to OpenProject’s main application elements:
Expand All @@ -384,8 +316,6 @@ All project menu items are spelled as in the application in bold, e.g.

- In the project menu, select **Work packages** to open your work package table.



### How to document a navigation path

To be consistent, use this format when you write about UI navigation. Use the same names as in the application in italic and with arrows in between:
Expand All @@ -398,7 +328,6 @@ Images, including screenshots, can help a reader better understand a guide. Howe

Before including an image in the documentation, ensure it provides value to the reader.


### Capture images

Use images to help the reader understand where they are in a process, or how they need to interact with the application.
Expand All @@ -409,7 +338,6 @@ When you take screenshots:

- Be consistent: Coordinate screenshots with the other screenshots already on a documentation page. For example, if other screenshots include the left sidebar, include the sidebar in all screenshots.


### Highlight specific areas and add numbered labels

You can highlight a specific area of a screenshot to draw the reader's attention to it. Additionally, add numbered labels to refer to specific parts of the screenshot in the documentation text. These should, however, be used sparingly, since any future changes to the interface require the highlighted areas and labels to be manually added to each updated screenshot.
Expand All @@ -428,7 +356,6 @@ This is an example of a screenshot with both highlighted areas and numbered labe

When referring to the numbered labels in the documentation text, use either an ordered list starting at number 1, with the numbers corresponding to the labeled parts of the screenshot. You may also refer to them within a line of text by using the word "Area" followed by the number, in parentheses, like so: "(Area 1)".


### Save images

- Save the image with a file name that describes the image. Use lower cases and no spaces (see [file names requirements](#directory-and-file-names)).
Expand All @@ -439,22 +366,16 @@ When referring to the numbered labels in the documentation text, use either an o

- Compress GIFs, maximum size 250KB.



### Add the image link to content

The Markdown code for including an image in a document is: `![Image description which will be the alt tag](document_image_title_v_x_y.png)`

The image description is the alt text for the rendered image on the documentation page. For accessibility and SEO, use descriptions that are short and precise.



## Videos

At the moment it is not possible for external contributors to upload videos to the documentation. Please open a ticket in case you want to add a video.



## Alert boxes

Use alert boxes to call attention to information. The alert boxes in the OpenProject documentation have a specific format. Please use the following to be consistent:
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/boards-introduction/README.md
View file
Expand Up @@ -10,7 +10,7 @@ keywords: Agile Boards

This document provides an initial introduction to the boards in OpenProject, i.e. how to use a Kanban board to manage your tasks in an agile way.

> **Note**: The basic agile boards are included in the OpenProject Community edition. OpenProject advanced Action boards are an Enterprise add-on and can only be used with [Enterprise cloud](https://www.openproject.org/docs/enterprise-guide/enterprise-cloud-guide) or [Enterprise on-premises](https://www.openproject.org/docs/enterprise-guide/enterprise-on-premises-guide). An upgrade from the free Community edition is easily possible.
> **Note**: The basic agile boards are included in the OpenProject Community edition. OpenProject advanced Action boards are an Enterprise add-on and can only be used with [Enterprise cloud](../../enterprise-guide/enterprise-cloud-guide) or [Enterprise on-premises](../../enterprise-guide/enterprise-on-premises-guide). An upgrade from the free Community edition is easily possible.


Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/my-account/README.md
View file
Expand Up @@ -156,7 +156,7 @@ You will then see a message informing you that the the token und the iCal URL ar

### OAUTH

OAuth tokens allow third-party applications to connect with this OpenProject instance, for example Nextcloud (see [here](../../user-guide/file-management/nextcloud-integration/) how to set up Nextcloud integration). OAuth tokens can be created under [*Administration-> Authentication*](https://www.openproject.org/docs/system-admin-guide/authentication/).
OAuth tokens allow third-party applications to connect with this OpenProject instance, for example Nextcloud (see [here](../../user-guide/file-management/nextcloud-integration/) how to set up Nextcloud integration). OAuth tokens can be created under [*Administration-> Authentication*](../../system-admin-guide/authentication/).

If no third-party application integration has been activated yet, this list will be empty. Please contact your administrator to help you set it up. Once an integration has been set up, you will see the details here and will be able to delete any OAuth tokens by clicking on the **Delete** icon.

Expand Down

0 comments on commit dcfa70e

Please sign in to comment.