[xwiki-devs] [Proposal] Always add a link to the reference doc in the RN items
Hi devs, This is something I mentioned a few times (just did on IRC/matrix an hour ago too) but I don’t know if we have an agreement about to, so I’m making a proposal. The idea is that I think it would be nice for users to be able to the read the RN and for each item to be able to navigate to the reference documentation to know more about the topic. Thus the proposal is to always add a link to the reference doc in RN items. For example I added a link here: https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/10.10RC1/#HAllo... When I created the RN app I had hesitate to have a field for that but I thought it be nicer if the links were in the text (better flow) and it would take less visual space (if we have a field we’ll need to add the info somewhere which will take more space). The downside is that everyone is forgetting to do it and it's not enforceable automatically. WDYT? Thanks -Vincent
Hello, +1 to enforce the link to the documentation. We could find a nice way to show the link by adding an icon next to the RN note or put the link on the title for instance. Thanks, Adel On Sun, Nov 18, 2018 at 2:56 PM Vincent Massol <[email protected]> wrote:
Hi devs,
This is something I mentioned a few times (just did on IRC/matrix an hour ago too) but I don’t know if we have an agreement about to, so I’m making a proposal.
The idea is that I think it would be nice for users to be able to the read the RN and for each item to be able to navigate to the reference documentation to know more about the topic.
Thus the proposal is to always add a link to the reference doc in RN items.
For example I added a link here: https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/10.10RC1/#HAllo...
When I created the RN app I had hesitate to have a field for that but I thought it be nicer if the links were in the text (better flow) and it would take less visual space (if we have a field we’ll need to add the info somewhere which will take more space). The downside is that everyone is forgetting to do it and it's not enforceable automatically.
WDYT?
Thanks -Vincent
+1 I agree this would help the user to find related information about the feature and the changes done. We already do this practice in the majority of cases. I would even say that when providing the link it would be great if we would add the version number in the link, for example https://www.xwiki.org/xwiki/bin/viewrev/Documentation/DevGuide/Tutorials/Wri... This way the release notes will be valid after 1 year or more. Because on xwiki.org we are supporting only the latest version, some documentation goes missing, some anchors get deleted, etc. Having the version number in the URL makes sure that the reader of the RN will know exactly how the documentation was indented to look like at the moment the feature was released. Thanks, Caty On Mon, Nov 19, 2018 at 11:15 AM Adel Atallah <[email protected]> wrote:
Hello,
+1 to enforce the link to the documentation.
We could find a nice way to show the link by adding an icon next to the RN note or put the link on the title for instance.
Thanks, Adel
On Sun, Nov 18, 2018 at 2:56 PM Vincent Massol <[email protected]> wrote:
Hi devs,
This is something I mentioned a few times (just did on IRC/matrix an
hour ago too) but I don’t know if we have an agreement about to, so I’m making a proposal.
The idea is that I think it would be nice for users to be able to the
read the RN and for each item to be able to navigate to the reference documentation to know more about the topic.
Thus the proposal is to always add a link to the reference doc in RN
items.
For example I added a link here:
https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/10.10RC1/#HAllo...
When I created the RN app I had hesitate to have a field for that but I
thought it be nicer if the links were in the text (better flow) and it would take less visual space (if we have a field we’ll need to add the info somewhere which will take more space). The downside is that everyone is forgetting to do it and it's not enforceable automatically.
WDYT?
Thanks -Vincent
+1 On Sun, Nov 18, 2018 at 3:56 PM Vincent Massol <[email protected]> wrote:
Hi devs,
This is something I mentioned a few times (just did on IRC/matrix an hour ago too) but I don’t know if we have an agreement about to, so I’m making a proposal.
The idea is that I think it would be nice for users to be able to the read the RN and for each item to be able to navigate to the reference documentation to know more about the topic.
Thus the proposal is to always add a link to the reference doc in RN items.
For example I added a link here:
https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/10.10RC1/#HAllo...
When I created the RN app I had hesitate to have a field for that but I thought it be nicer if the links were in the text (better flow) and it would take less visual space (if we have a field we’ll need to add the info somewhere which will take more space). The downside is that everyone is forgetting to do it and it's not enforceable automatically.
WDYT?
Thanks -Vincent
Since the documentation url is already filled in our jira issue, could we associate the issue number to Release Notes change, and so the url of the documentation is automatically pulled from jira ? This way we could also add a link to the jira issue. My 2 cents, Le mar. 20 nov. 2018 à 13:12, Marius Dumitru Florea < [email protected]> a écrit :
+1
On Sun, Nov 18, 2018 at 3:56 PM Vincent Massol <[email protected]> wrote:
Hi devs,
This is something I mentioned a few times (just did on IRC/matrix an hour ago too) but I don’t know if we have an agreement about to, so I’m making a proposal.
The idea is that I think it would be nice for users to be able to the read the RN and for each item to be able to navigate to the reference documentation to know more about the topic.
Thus the proposal is to always add a link to the reference doc in RN items.
For example I added a link here:
https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/10.10RC1/#HAllo...
When I created the RN app I had hesitate to have a field for that but I thought it be nicer if the links were in the text (better flow) and it would take less visual space (if we have a field we’ll need to add the
info
somewhere which will take more space). The downside is that everyone is forgetting to do it and it's not enforceable automatically.
WDYT?
Thanks -Vincent
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
It's certainly nicer to have a link to the documentation. Now not sure it's really work all the time and how to show it best, also we need to support several link for the same entry since a RN entry often contain several things in the same domain. On Tue, Nov 20, 2018 at 1:21 PM Guillaume Delhumeau <[email protected]> wrote:
Since the documentation url is already filled in our jira issue, could we associate the issue number to Release Notes change, and so the url of the documentation is automatically pulled from jira ? This way we could also add a link to the jira issue.
My 2 cents,
Le mar. 20 nov. 2018 à 13:12, Marius Dumitru Florea < [email protected]> a écrit :
+1
On Sun, Nov 18, 2018 at 3:56 PM Vincent Massol <[email protected]> wrote:
Hi devs,
This is something I mentioned a few times (just did on IRC/matrix an hour ago too) but I don’t know if we have an agreement about to, so I’m making a proposal.
The idea is that I think it would be nice for users to be able to the read the RN and for each item to be able to navigate to the reference documentation to know more about the topic.
Thus the proposal is to always add a link to the reference doc in RN items.
For example I added a link here:
https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/10.10RC1/#HAllo...
When I created the RN app I had hesitate to have a field for that but I thought it be nicer if the links were in the text (better flow) and it would take less visual space (if we have a field we’ll need to add the
info
somewhere which will take more space). The downside is that everyone is forgetting to do it and it's not enforceable automatically.
WDYT?
Thanks -Vincent
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
-- Thomas Mortagne
participants (6)
-
Adel Atallah -
Ecaterina Moraru (Valica) -
Guillaume Delhumeau -
Marius Dumitru Florea -
Thomas Mortagne -
Vincent Massol