# OpenProject: a practical guide for Alkemata contributors

_25 October 2026 · For everyday use of Website alkemata. No installation steps._

## Start here: your first useful contribution

Open [Alkemata Projects](https://projects.alkemata.com/), sign in with your Alkemata account, and select **Website alkemata**. Choose **Work packages** to see tasks and **Wiki** to read documentation.

Try this small exercise: open [Documentation #39](https://projects.alkemata.com/work_packages/39), read its current content, then use the instructions below to propose a specific improvement, record the result, and link the relevant wiki page. The examples in this tutorial are suggestions: they have not been created as extra tasks.

The project currently offers **Task**, **Milestone**, and **Summary task** types. Button labels can vary with language and version. Work packages and Wiki are enabled; other modules mentioned below depend on project settings and permissions.

## 1. Decide where something belongs

| What you want to record | Where to put it | Alkemata example |
| --- | --- | --- |
| An action with an owner and an outcome | Work package | Check the map link on mobile |
| A larger area divided into actions | Parent work package with children | Documentation → contributor guide, review, corrections |
| A target event or delivery date | Milestone | Contributor guide ready |
| Instructions or a durable decision | Wiki page | How to submit an article |
| A question or progress update about one task | That task's Activity comments | Review requested; two links still need checking |
| Evidence or a deliverable | Task attachment or a link to its source | Screenshot, test report, design file |

A work package is OpenProject's general term for a tracked item. Give each actionable task one clear outcome. Prefer “Test login with a new contributor account” to “Login stuff”.

[Official introduction](https://www.openproject.org/docs/user-guide/work-packages/)

## 2. Create and assign a task

1. In **Website alkemata → Work packages**, click **+ Create** and choose **Task**.
2. Enter a subject, for example **Write a contributor onboarding guide**.
3. Add a description using the template below.
4. Choose an **Assignee** from project members; set a realistic finish date and priority if needed.
5. Click **Save** and keep the task's link for discussion.

**Description template**

- **Goal:** A new contributor can find a task, submit work, and request review.
- **Deliverable:** One wiki page linked from the relevant task.
- **Done when:** A second person follows the steps successfully; links work; open questions are listed.
- **Resources:** Relevant pages, examples, and source documents.
- **Next action:** Draft the first three steps.

The assignee does the work. If an Accountable field is available, use it for the person responsible for the outcome. If the person you need is missing, first check that the correct project is selected, then ask a project manager to check membership.

[Create work packages](https://www.openproject.org/docs/user-guide/work-packages/create-work-package/)

## 3. Break a large task into small pieces

Use [Documentation #39](https://projects.alkemata.com/work_packages/39) as an existing parent if that matches the team's plan.

1. Open the parent work package.
2. Use its menu's **Create new child** action, where available, to add a smaller task.
3. Alternatively, create the task first, open **Relations**, and add **Parent**, selecting Documentation by its ID or subject.
4. Check that the hierarchy shows the intended parent.

Example children: **Draft contributor guide**, **Check guide as a new user**, **Apply review corrections**. Give each its own assignee and completion criteria.

Use a parent-child relationship for “part of”. Use a predecessor/successor relation for “must happen before”. A documentation task can be part of Documentation while also following a separate testing task.

[Relations and hierarchies](https://www.openproject.org/docs/user-guide/work-packages/work-package-relations-hierarchies/)

## 4. Update progress and ask for help

Open a task and click its current **Status** to choose an allowed next status. The available transitions depend on its type and your role; use the options actually offered.

In **Activity**, add a short comment:

> Draft ready: [paste wiki URL]. Please check the first-login instructions. Remaining issue: confirm the review contact.

Type **@** and select a member when asking for a specific response. Keep the description as the current agreed scope; use comments for progress and discussion.

If blocked, record **what is missing, who can help, and the next step**. Do not mark a task complete just because a draft exists: compare the result with “Done when”, attach evidence, and request review. Once accepted, select the appropriate closed status.

[Editing, comments, and mentions](https://www.openproject.org/docs/user-guide/work-packages/edit-work-package/)

## 5. Find your work without scrolling

1. Open **Work packages**.
2. Add an **Assignee** filter for yourself and a **Status** filter for open work.
3. Open the table configuration, usually under the three-dot menu or settings control.
4. Show useful columns: Subject, Status, Assignee, Priority, Start date, Finish date, and Parent.
5. Sort by finish date; group by assignee or status when useful.
6. Save the view as **My open work**, using the available save-view action.

Create another view for the team: open tasks, grouped by assignee, with upcoming dates visible. Choose public visibility only when you intend other permitted users to reuse that view; a public view does not grant access to a private project.

If a task disappears, remove filters before assuming it was deleted. Closed tasks are often excluded.

[Filters, columns, grouping, and saved views](https://www.openproject.org/docs/user-guide/work-packages/work-package-table-configuration/)

## 6. Plan dates and dependencies

If **Gantt charts** appears in the project menu:

1. Open it and find the tasks you want to plan.
2. Set start and finish dates, either in the table/details or by positioning and resizing timeline bars.
3. For a genuine sequence, right-click the first item and choose **Add successor**, then select the following item.
4. Add a **Milestone** for a delivery checkpoint, such as **Contributor guide accepted**.
5. Check the resulting sequence and dates.

Example: **Draft guide → Test instructions → Apply corrections → Guide accepted**.

The Gantt chart shows the same work packages as the task table. Editing one updates the shared task. Working days affect duration; check the displayed dates after dragging bars. Scheduling mode affects how dependent dates move, so inspect the result rather than assuming every change propagates.

[Official Gantt guide](https://www.openproject.org/docs/user-guide/gantt-chart/)

## 7. Use a board when visual organisation helps

If **Boards** is enabled:

1. Open **Boards**, create a **Basic board**, and name it **Documentation flow**.
2. Add lists such as **To do**, **Working**, and **Ready for review**.
3. Add existing work packages to the lists.
4. Move cards as your work progresses.

Moving a card on a Basic board does not automatically change the work package's status. Update Status separately.

Removing a card from a board does not delete the underlying task. Use the task table and its Status field as the reliable progress record if maintaining both becomes cumbersome.

[Official board guide](https://www.openproject.org/docs/user-guide/agile-boards/)

## 8. Write and maintain a wiki page

1. Open **Wiki** and use **+ Wiki page** or the available create-page action.
2. Give it a specific title, such as **Contributor onboarding**.
3. Write the purpose, prerequisites, numbered steps, expected result, and useful links.
4. Save, reopen, and check the formatting and links.
5. Copy the page URL into the related work package.

To improve an existing page, open it and choose **Edit**. Use headings and short procedures. Add a link to another page using the editor's link controls or wiki syntax such as `[[Contributor onboarding]]`.

Suggested page structure: **Purpose → Before you start → Steps → How to check success → Common problems → Resources**.

Keep decisions and reusable instructions here so they remain findable after a task closes. For technical background, see [Alkemata server architecture and project inventory](https://projects.alkemata.com/projects/website-alkemata/wiki/alkemata-server-architecture-and-project-inventory).

[Official wiki guide](https://www.openproject.org/docs/user-guide/wiki/)

## 9. Share files and deliverables

Open a work package's **Files** tab and use **Attach files** or drag and drop, if uploads are enabled. Name files clearly, for example `contributor-guide-review-2026-10-25.pdf`, and explain their purpose in a comment.

For a document already maintained elsewhere, paste its canonical link and check that reviewers can open it. Keep one authoritative editable copy. Attachments are useful for evidence and snapshots; uploading a file does not by itself create a Git-like document editing workflow.

If Nextcloud or another file storage is configured, use its integration for linked files; do not assume that integration is available merely because OpenProject supports it.

[Attachment instructions](https://www.openproject.org/docs/user-guide/work-packages/create-work-package/)

## 10. Collaborate with other people and agents

**People:** a project manager can open **Members**, add an existing user or invite a new one where permitted, and assign a suitable role. Account creation and project membership are separate: signing in alone does not guarantee access. Give contributors the rights they need to work and reviewers the rights they need to review.

[Member management](https://www.openproject.org/docs/user-guide/members/)

**AI assistants:** Alkemata's private MCP tools currently support listing projects, reading/creating/editing work packages, and reading/creating/editing wiki pages under the connected user's permissions. Example request:

> In Website alkemata, read Documentation #39 and the existing wiki pages. Draft a task description with acceptance criteria, then update that task and link this tutorial. Preserve existing material.

Be explicit about whether the assistant should draft or save changes. The exposed tools do not currently offer assignee/date editing, file uploads, or comment creation; perform those steps in the browser. Agents use the same project access rules as the signed-in user.

## 11. Keep notifications useful

In your account menu, open **Account settings → Notification and email**. Choose the events and email frequency that fit your work. Follow/watch the tasks you need to review where that control is available.

Use mentions for a concrete question or review request. Check notifications regularly, but keep the final answer or decision on the task or wiki page so another contributor can find it.

[Notification settings](https://www.openproject.org/docs/user-guide/account-settings/notification-and-email/)

## 12. A simple weekly routine

- **Start:** open your saved view; pick a small task; confirm its outcome and owner.
- **During work:** update the task, record blockers, and link results.
- **Before closing:** compare against completion criteria and obtain review where needed.
- **Weekly:** check overdue work, unassigned tasks, and decisions that belong in the wiki.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| Website alkemata is missing | Check the signed-in account and ask a manager to check project membership. |
| A create/edit button is absent | Check your project role; ask a manager to check permissions or whether the module is enabled. |
| A status is unavailable | Use a permitted transition; ask about the configured workflow if it prevents the intended action. |
| A task is missing from a view | Clear filters, include closed statuses, and confirm the project. |
| An assignee is unavailable | Select the project first; check membership. |
| Gantt or Boards is absent | Ask whether the project module is enabled; continue with Work packages. |
| A saved edit conflicts | Reload the latest content, compare changes, and reapply your edit without overwriting another contributor's work. |

For broader reference, use the [official user guide](https://www.openproject.org/docs/user-guide/) and [getting-started tutorials and videos](https://www.openproject.org/docs/getting-started/). This tutorial uses the live project inventory and official documentation checked on 25 October 2026; the official website may describe a newer interface.