[Proposal] Always add a link to the reference doc in the RN items

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

[Proposal] Always add a link to the reference doc in the RN items

vmassol
Administrator
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/#HAllowwikimacrostoindicatethetypeofparameters

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

Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Always add a link to the reference doc in the RN items

Adel Atallah
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 <[hidden email]> 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/#HAllowwikimacrostoindicatethetypeofparameters
>
> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Always add a link to the reference doc in the RN items

Ecaterina Moraru (Valica)
+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/WritingMacros/WikiMacroTutorial/WebHome?rev=98.4#HParameters

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 <[hidden email]>
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 <[hidden email]> 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/#HAllowwikimacrostoindicatethetypeofparameters
> >
> > 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
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Always add a link to the reference doc in the RN items

Marius Dumitru Florea
In reply to this post by vmassol
+1

On Sun, Nov 18, 2018 at 3:56 PM Vincent Massol <[hidden email]> 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/#HAllowwikimacrostoindicatethetypeofparameters
>
> 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
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Always add a link to the reference doc in the RN items

Guillaume Delhumeau
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 <
[hidden email]> a écrit :

> +1
>
> On Sun, Nov 18, 2018 at 3:56 PM Vincent Massol <[hidden email]> 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/#HAllowwikimacrostoindicatethetypeofparameters
> >
> > 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 ([hidden email])
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Always add a link to the reference doc in the RN items

Thomas Mortagne
Administrator
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
<[hidden email]> 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 <
> [hidden email]> a écrit :
>
> > +1
> >
> > On Sun, Nov 18, 2018 at 3:56 PM Vincent Massol <[hidden email]> 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/#HAllowwikimacrostoindicatethetypeofparameters
> > >
> > > 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 ([hidden email])
> Research & Development Engineer at XWiki SAS
> Committer on the XWiki.org project



--
Thomas Mortagne