10 Jul
2013
10 Jul
'13
4:57 p.m.
On Jul 10, 2013, at 4:35 PM, Marius Dumitru Florea <mariusdumitru.florea(a)xwiki.com>
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
<vincent(a)massol.net> wrote:
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
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