[xwiki-devs] [Brainstorming] Structuring features/improvements on xwiki.org
Hi devs, Today I needed to see all the features that were added since XWiki 2.4 and that got me thinking about how to document new feature or improvements on xwiki.org. I started imagining the following: * To have an xclass representing an improvement or feature, with several properties: - the version in which the feature or improvement was added - whether it's an improvement or a feature - the description of the improvement or feature (textarea), in wiki syntax * On a given page, add as many xobjects that there are features or improvements * Create a wiki macro to include the xobject's content in the page content so that the user can see it when viewing the page Pros: * This would allow to be able to query the full wiki to see all the features/improvements added in a given version * This would allow to auto generate the release notes :) We wouldn't need to duplicate the content in both the release notes and in the reference document. * This would allow to automatically add some "new" icons when the version corresponding to the improvement/new feature is newer than the baseline version (for example, if we're developing version N we can say that on xwiki.org we consider a feature/improvement to be "new" when its corresponding version is >= N-2) Cons: * A lot of work to convert the existing xwiki.org content to this but we don't need to do that upfront. We can start by agreeing that any new feature/improvement would go through this mechanism for example. * A bit more complex to add new content for users but this mechanism doesn't preclude using the current way (ie unstructured content) as it'll still work. WDYT? Do you think this could be useful? Thanks -Vincent
I also looked for new features since 2.4, but I've used JIRA for this and filtered on the issue type. Thanks, Caty On Wed, Jul 10, 2013 at 3:24 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Today I needed to see all the features that were added since XWiki 2.4 and that got me thinking about how to document new feature or improvements on xwiki.org.
I started imagining the following:
* To have an xclass representing an improvement or feature, with several properties: - the version in which the feature or improvement was added - whether it's an improvement or a feature - the description of the improvement or feature (textarea), in wiki syntax
* On a given page, add as many xobjects that there are features or improvements * Create a wiki macro to include the xobject's content in the page content so that the user can see it when viewing the page
Pros: * This would allow to be able to query the full wiki to see all the features/improvements added in a given version * This would allow to auto generate the release notes :) We wouldn't need to duplicate the content in both the release notes and in the reference document. * This would allow to automatically add some "new" icons when the version corresponding to the improvement/new feature is newer than the baseline version (for example, if we're developing version N we can say that on xwiki.org we consider a feature/improvement to be "new" when its corresponding version is >= N-2)
Cons: * A lot of work to convert the existing xwiki.org content to this but we don't need to do that upfront. We can start by agreeing that any new feature/improvement would go through this mechanism for example. * A bit more complex to add new content for users but this mechanism doesn't preclude using the current way (ie unstructured content) as it'll still work.
WDYT? Do you think this could be useful?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Jul 10, 2013, at 2:39 PM, "Ecaterina Moraru (Valica)" <[email protected]> wrote:
I also looked for new features since 2.4, but I've used JIRA for this and filtered on the issue type.
Sure but that's not really my point. That was just what got me thinking :) Any feedback on the idea below? Thanks -Vincent
Thanks, Caty
On Wed, Jul 10, 2013 at 3:24 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Today I needed to see all the features that were added since XWiki 2.4 and that got me thinking about how to document new feature or improvements on xwiki.org.
I started imagining the following:
* To have an xclass representing an improvement or feature, with several properties: - the version in which the feature or improvement was added - whether it's an improvement or a feature - the description of the improvement or feature (textarea), in wiki syntax
* On a given page, add as many xobjects that there are features or improvements * Create a wiki macro to include the xobject's content in the page content so that the user can see it when viewing the page
Pros: * This would allow to be able to query the full wiki to see all the features/improvements added in a given version * This would allow to auto generate the release notes :) We wouldn't need to duplicate the content in both the release notes and in the reference document. * This would allow to automatically add some "new" icons when the version corresponding to the improvement/new feature is newer than the baseline version (for example, if we're developing version N we can say that on xwiki.org we consider a feature/improvement to be "new" when its corresponding version is >= N-2)
Cons: * A lot of work to convert the existing xwiki.org content to this but we don't need to do that upfront. We can start by agreeing that any new feature/improvement would go through this mechanism for example. * A bit more complex to add new content for users but this mechanism doesn't preclude using the current way (ie unstructured content) as it'll still work.
WDYT? Do you think this could be useful?
Thanks -Vincent
What would be the granularity of the features? "Extension Manager" vs. {"Search Extensions", "Install Extensions", "Uninstall Extensions", ...}? And, when you have a feature that is improved over time, do we keep the initial description of the feature and the description of all the improvements unchanged? How will this look on the documentation page? It will be confusing if we simply display the (initial) feature description followed by all the improvements. On Wed, Jul 10, 2013 at 3:24 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Today I needed to see all the features that were added since XWiki 2.4 and that got me thinking about how to document new feature or improvements on xwiki.org.
I started imagining the following:
* To have an xclass representing an improvement or feature, with several properties: - the version in which the feature or improvement was added - whether it's an improvement or a feature - the description of the improvement or feature (textarea), in wiki syntax
* On a given page, add as many xobjects that there are features or improvements * Create a wiki macro to include the xobject's content in the page content so that the user can see it when viewing the page
Pros: * This would allow to be able to query the full wiki to see all the features/improvements added in a given version
* This would allow to auto generate the release notes :) We wouldn't need to duplicate the content in both the release notes and in the reference document.
This should not happen as we are supposed to write the information in the documentation page and just put a mention with a link (and maybe a global screenshot) in the release notes. Thanks, Marius
* This would allow to automatically add some "new" icons when the version corresponding to the improvement/new feature is newer than the baseline version (for example, if we're developing version N we can say that on xwiki.org we consider a feature/improvement to be "new" when its corresponding version is >= N-2)
Cons: * A lot of work to convert the existing xwiki.org content to this but we don't need to do that upfront. We can start by agreeing that any new feature/improvement would go through this mechanism for example. * A bit more complex to add new content for users but this mechanism doesn't preclude using the current way (ie unstructured content) as it'll still work.
WDYT? Do you think this could be useful?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Jul 10, 2013, at 4:35 PM, Marius Dumitru Florea <[email protected]> wrote:
What would be the granularity of the features? "Extension Manager" vs. {"Search Extensions", "Install Extensions", "Uninstall Extensions", ...}? And, when you have a feature that is improved over time, do we keep the initial description of the feature and the description of all the improvements unchanged? How will this look on the documentation page? It will be confusing if we simply display the (initial) feature description followed by all the improvements.
Yes, we would need to go smaller than "Extension Manager" IMO. As you say "Searching an Extension" for example. But maybe the granularity is something that depends on what is being documented. Now say, we have implemented "Searching an extension" in 4.0 and later on we change that feature, we could just have a new xobject with a version of 5.0 (for ex). The main content would reference the newest version. The old version will no longer be displayed but can still be found with searching. This brings complex questions actually… I wonder if we can have something that's not too complex… From the outset it seems it would be complex. It would still be nice to be able to identify portions of texts that are only valid for a given version. Maybe a macro is enough for that. {{version id="5.2"}} …. {{/version}} The only pity is that we cannot do a search on all version macros across all pages for a given id.
On Wed, Jul 10, 2013 at 3:24 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Today I needed to see all the features that were added since XWiki 2.4 and that got me thinking about how to document new feature or improvements on xwiki.org.
I started imagining the following:
* To have an xclass representing an improvement or feature, with several properties: - the version in which the feature or improvement was added - whether it's an improvement or a feature - the description of the improvement or feature (textarea), in wiki syntax
* On a given page, add as many xobjects that there are features or improvements * Create a wiki macro to include the xobject's content in the page content so that the user can see it when viewing the page
Pros: * This would allow to be able to query the full wiki to see all the features/improvements added in a given version
* This would allow to auto generate the release notes :) We wouldn't need to duplicate the content in both the release notes and in the reference document.
This should not happen as we are supposed to write the information in the documentation page and just put a mention with a link (and maybe a global screenshot) in the release notes.
Yes indeed, there's still the need for a summary and whether it's located in the RN or in the xobject it's still needed… So it doesn't really help for this use case. Ok, so maybe it's not the right solution and the solution is to continue the Release Notes Application I have started instead, i.e. do what I have described but at the level of the release notes pages only. That + the {{version}} macros will allow to answer the questions: * What's been done since XWiki 2.4 * Match content with a version of XWiki when viewing a page * Auto generate RN pages, especially release notes for final releases Thanks -Vincent
Thanks, Marius
* This would allow to automatically add some "new" icons when the version corresponding to the improvement/new feature is newer than the baseline version (for example, if we're developing version N we can say that on xwiki.org we consider a feature/improvement to be "new" when its corresponding version is >= N-2)
Cons: * A lot of work to convert the existing xwiki.org content to this but we don't need to do that upfront. We can start by agreeing that any new feature/improvement would go through this mechanism for example. * A bit more complex to add new content for users but this mechanism doesn't preclude using the current way (ie unstructured content) as it'll still work.
WDYT? Do you think this could be useful?
Thanks -Vincent
On Wed, Jul 10, 2013 at 5:57 PM, Vincent Massol <[email protected]> wrote:
On Jul 10, 2013, at 4:35 PM, Marius Dumitru Florea <[email protected]> wrote:
What would be the granularity of the features? "Extension Manager" vs. {"Search Extensions", "Install Extensions", "Uninstall Extensions", ...}? And, when you have a feature that is improved over time, do we keep the initial description of the feature and the description of all the improvements unchanged? How will this look on the documentation page? It will be confusing if we simply display the (initial) feature description followed by all the improvements.
Yes, we would need to go smaller than "Extension Manager" IMO. As you say "Searching an Extension" for example. But maybe the granularity is something that depends on what is being documented.
Now say, we have implemented "Searching an extension" in 4.0 and later on we change that feature, we could just have a new xobject with a version of 5.0 (for ex). The main content would reference the newest version. The old version will no longer be displayed but can still be found with searching.
This brings complex questions actually… I wonder if we can have something that's not too complex… From the outset it seems it would be complex.
It would still be nice to be able to identify portions of texts that are only valid for a given version. Maybe a macro is enough for that.
{{version id="5.2"}} …. {{/version}}
Or maybe annotations? A mix between annotations and tags actually, but I'm not sure how it will evolve when the content changes.
The only pity is that we cannot do a search on all version macros across all pages for a given id.
On Wed, Jul 10, 2013 at 3:24 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Today I needed to see all the features that were added since XWiki 2.4 and that got me thinking about how to document new feature or improvements on xwiki.org.
I started imagining the following:
* To have an xclass representing an improvement or feature, with several properties: - the version in which the feature or improvement was added - whether it's an improvement or a feature - the description of the improvement or feature (textarea), in wiki syntax
* On a given page, add as many xobjects that there are features or improvements * Create a wiki macro to include the xobject's content in the page content so that the user can see it when viewing the page
Pros: * This would allow to be able to query the full wiki to see all the features/improvements added in a given version
* This would allow to auto generate the release notes :) We wouldn't need to duplicate the content in both the release notes and in the reference document.
This should not happen as we are supposed to write the information in the documentation page and just put a mention with a link (and maybe a global screenshot) in the release notes.
Yes indeed, there's still the need for a summary and whether it's located in the RN or in the xobject it's still needed… So it doesn't really help for this use case.
Ok, so maybe it's not the right solution and the solution is to continue the Release Notes Application I have started instead, i.e. do what I have described but at the level of the release notes pages only.
That + the {{version}} macros will allow to answer the questions: * What's been done since XWiki 2.4 * Match content with a version of XWiki when viewing a page * Auto generate RN pages, especially release notes for final releases
Thanks -Vincent
Thanks, Marius
* This would allow to automatically add some "new" icons when the version corresponding to the improvement/new feature is newer than the baseline version (for example, if we're developing version N we can say that on xwiki.org we consider a feature/improvement to be "new" when its corresponding version is >= N-2)
Cons: * A lot of work to convert the existing xwiki.org content to this but we don't need to do that upfront. We can start by agreeing that any new feature/improvement would go through this mechanism for example. * A bit more complex to add new content for users but this mechanism doesn't preclude using the current way (ie unstructured content) as it'll still work.
WDYT? Do you think this could be useful?
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Same concern as Marius. The idea sounds for the release notes but big -1 to have documentation based on this. On Wed, Jul 10, 2013 at 4:35 PM, Marius Dumitru Florea <[email protected]> wrote:
What would be the granularity of the features? "Extension Manager" vs. {"Search Extensions", "Install Extensions", "Uninstall Extensions", ...}? And, when you have a feature that is improved over time, do we keep the initial description of the feature and the description of all the improvements unchanged? How will this look on the documentation page? It will be confusing if we simply display the (initial) feature description followed by all the improvements.
On Wed, Jul 10, 2013 at 3:24 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Today I needed to see all the features that were added since XWiki 2.4 and that got me thinking about how to document new feature or improvements on xwiki.org.
I started imagining the following:
* To have an xclass representing an improvement or feature, with several properties: - the version in which the feature or improvement was added - whether it's an improvement or a feature - the description of the improvement or feature (textarea), in wiki syntax
* On a given page, add as many xobjects that there are features or improvements * Create a wiki macro to include the xobject's content in the page content so that the user can see it when viewing the page
Pros: * This would allow to be able to query the full wiki to see all the features/improvements added in a given version
* This would allow to auto generate the release notes :) We wouldn't need to duplicate the content in both the release notes and in the reference document.
This should not happen as we are supposed to write the information in the documentation page and just put a mention with a link (and maybe a global screenshot) in the release notes.
Thanks, Marius
* This would allow to automatically add some "new" icons when the version corresponding to the improvement/new feature is newer than the baseline version (for example, if we're developing version N we can say that on xwiki.org we consider a feature/improvement to be "new" when its corresponding version is >= N-2)
Cons: * A lot of work to convert the existing xwiki.org content to this but we don't need to do that upfront. We can start by agreeing that any new feature/improvement would go through this mechanism for example. * A bit more complex to add new content for users but this mechanism doesn't preclude using the current way (ie unstructured content) as it'll still work.
WDYT? Do you think this could be useful?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
participants (4)
-
Ecaterina Moraru (Valica) -
Marius Dumitru Florea -
Thomas Mortagne -
Vincent Massol