How to deal with documented features that are not released yet? #548

New Issue

2024-01-08T14:43:41Z

p4u1 commented

2024-01-08 14:43:41 +00:00

Background:

In coop-cloud/organising#543 a user reported that a documented feature is not working. The problem was, that the feature is not released yet (needs an abra release). But the documentation change got merged already

Solution 1:

Don't merge documentation changes for new features directly. After a new abra release merge all documentation changes.

Pro:

very easy to implement

Con:

Merge conflicts might appear and can create a lot of burden on the person doing the release
When a user visits the docs, the don't know for sure if the feature they are looking for is release in their local version of abra, since thei might not have the latest

Solution 1.1:

Merge all documentation changes for new features in a new branch (e.g. abra-0.9.0). After the release merge the branch into the main branch

Pro:

very easy to implement

Con:

Merge conflicts might appear and can create a lot of burden on the person doing the release (There should be fewer conflicts than in Solution 1)
When a user visits the docs, they don't know for sure if the feature they are looking for is release in their local version of abra, since they might not have the latest

Solution 2:

When documenting a new feature also add the abra version it is/will be available in.

Pro:

very easy to implement
Very clear for the user

Con:

After some released versions the info about when the feature first got available might not be so relevant anymore. It makes the docs more verbose in general

Solution 3:

Every abra version gets its own documentation. There is a drop down menu on the docs site to specify the abra version.

Pro:

Easy on the release maintainer
Not verbose for the user

Con:

Effort is needed to add this feature to the docs site (Note that not every documentation page is bound to a abra version which makes the implementation more complicated)

Discussion

If think we should tackle this problem but I'm not sure about the best solution. If you come up with another viable solution please also post it as a comment. Also please discuss the proposed solutions so we can agree on one :)

### **Background:** In https://git.coopcloud.tech/coop-cloud/organising/issues/543 a user reported that a documented feature is not working. The problem was, that the feature is not released yet (needs an abra release). But the documentation change got merged already ### **Solution 1:** Don't merge documentation changes for new features directly. After a new abra release merge all documentation changes. _Pro:_ - very easy to implement _Con:_ - Merge conflicts might appear and can create a lot of burden on the person doing the release - When a user visits the docs, the don't know for sure if the feature they are looking for is release in their local version of abra, since thei might not have the latest ### **Solution 1.1:** Merge all documentation changes for new features in a new branch (e.g. `abra-0.9.0`). After the release merge the branch into the main branch _Pro:_ - very easy to implement _Con:_ - Merge conflicts might appear and can create a lot of burden on the person doing the release (There should be fewer conflicts than in Solution 1) - When a user visits the docs, they don't know for sure if the feature they are looking for is release in their local version of abra, since they might not have the latest ### **Solution 2:** When documenting a new feature also add the abra version it is/will be available in. _Pro:_ - very easy to implement - Very clear for the user _Con:_ - After some released versions the info about when the feature first got available might not be so relevant anymore. It makes the docs more verbose in general ### **Solution 3:** Every abra version gets its own documentation. There is a drop down menu on the docs site to specify the abra version. _Pro:_ - Easy on the release maintainer - Not verbose for the user _Con:_ - Effort is needed to add this feature to the docs site (Note that not every documentation page is bound to a abra version which makes the implementation more complicated) ### Discussion If think we should tackle this problem but I'm not sure about the best solution. If you come up with another viable solution please also post it as a comment. Also please discuss the proposed solutions so we can agree on one :)

p4u1 changed title from ~~How to deal with documented featured that are not released yet?~~ to How to deal with documented features that are not released yet?

2024-01-08 14:43:56 +00:00

decentral1se commented

2024-01-08 14:56:25 +00:00

Nice. I think solution 2 is the best since anyone can run abra -v and know what is relevant.

Nice. I think solution 2 is the best since anyone can run `abra -v` and know what is relevant.

👍 1

3wordchant commented

2024-02-10 21:34:30 +00:00

Agreed. Mkdocs-material seems to support a nice md-version thing for this (e.g. see https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#admonition) but I can't work out how to turn it on 🤔

Agreed. Mkdocs-material seems to support a nice `md-version` thing for this (e.g. see https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#admonition) but I can't work out how to turn it on 🤔 ![image](/attachments/9d928aab-21de-4ba8-8d9a-ef87cf4e98c4)

image.png

32 KiB

decentral1se commented

2024-03-27 06:15:07 +00:00

Aight cool, let's do this in the future then! Starting with 7675df7d7c.

Aight cool, let's do this in the future then! Starting with https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/commit/7675df7d7ca993ee2bdd4b0de8416382f3b812dd.

decentral1se closed this issue

2024-03-27 06:15:07 +00:00

Sign in to join this conversation.

3 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: toolshed/organising#548