19 Sep
2016
19 Sep
'16
4:33 p.m.
I've re-read your answer about "The idea now is more that he release notes
should focus on summarizing the changes rather than documenting them.". In
this case instead of ExtensionFeatureClass, we could have something like
ExtensionFeatureSummaryClass or ExtensionFeatureHighlightClass. My only
point is that I don't understand why we would use a different application,
instead of extending the Repo app and keep all related things together (the
only problem is having too many objects for a particular page).
Thanks,
Caty
On Mon, Sep 19, 2016 at 5:24 PM, Ecaterina Moraru (Valica) <
valicac(a)gmail.com> wrote:
If we extend the Repo app and create this
ExtensionFeatureClass that
contains all your XProperties (except Category) than we can include them
easily in the RN and Documentation.
We kind of have a "practice" to use something like "Since 8.3M2"
(example
in http://extensions.xwiki.org/xwiki/bin/view/Extension/
Administration+Application) that could be generated from these types of
objects, using different layouts depending if we are in RN or
documentation.
I'm stopping :) but the thing is that no matter how we implement the
application is going to be useful to be able to filter
features/versions/extension. So I'm excited to see it happen.
Thanks,
Caty
On Mon, Sep 19, 2016 at 5:02 PM, Ecaterina Moraru (Valica) <
valicac(a)gmail.com> wrote:
Why don't we just improve this class
http://extensions.xwiki.org/xw
iki/bin/view/ExtensionCode/ExtensionVersionClass ?
Maybe the difference is that this is per version and you kind of want per
functionality.
But the 'Category' is not needed, since we have the extension page name.
The idea is that I would really want us to see if we could use this
application also in the future, to document things for the extensions
pages.
Thanks,
Caty
On Mon, Sep 19, 2016 at 3:13 PM, Ecaterina Moraru (Valica) <
valicac(a)gmail.com> wrote:
On Fri, Sep 16, 2016 at 7:18 PM, Vincent Massol <vincent(a)massol.net>
wrote:
Hi devs,
I’m planning to write a Release Notes Application for xwiki.org. I’d
like to do something relatively simple in order to have a first working
version.
Rationale
========
* Have nicer looking release notes by defining a structure and a common
L&F
* For users, be able to see all the release notes item from a given
version to another version and by category
Idea
====
Specifically for the “New and Networthy" section have:
- A visual that looks like this: https://www.jetbrains.com/data
grip/features/
- 2 columns layout
- For each item a screenshot and a summary text
- (optional) Have a “Learn more” button that goes to the item and
provides more info (and possibly more screenshots if need be)
XProperties:
- Version (in which the item has been added). Static list
- Category (Help, Color Themes, Solr Search, AWM, etc). Static list
- Main screenshot
- Summary text
- Additional content
- Target audience (User, Admin, Developer). Static list
Notes:
- If no “main screenshot” is provided then the generated report will
put the item in a Miscellaneous section
For now I don’t want to handle other metadata for the releases notes,
i.e. translations, upgrades, backward compat, tested browsers, etc).
Precisely, I’m planning to write a “New and Networthy” application ATM, not
a full “Release notes app”.
The way it could be used is through a {{news/}} macro, e.g.: {{news
from=“6.4” to=“8.2” [categories=“help,awm,...”]
[targetAudience=“user,admin”] /}}.
Usage
======
- There would be a page in the wiki to see the livetable corresponding
to all the release notes news (the xproperties above)
- Above this Livetable I imagine a form with several fields:
— From version,
— To Version
— Category (if not empty generate the report only for that category)
— Target (user, admin, dev). (if not empty only generate the report for
that target audience)
— + a “Generate” button to generate a dynamic "News and Networthy”
report
- We would also use Tags for each news to categorize it further, e.g.
“usability”, “performance”, and the LT would display the tag cloud. This
will allow for example to see all items between such version and such
version that are related to, say, performance
- We would still write a Release Notes page for each version but on
that page, we would use the {{news/}} macro (with from = to = the version
corresponding to that RN). On that page we would add all the other parts
that are not in the app yet, i.e. translations, upgrades, backward compat,
etc
- When an XWiki developers codes a new feature or improvement or new
API will use the app to add it.
Future
======
* Add a different release notes app to include the other metadata
* We could almost imagine using this “New and networthy” app to provide
reference documentation for our features… :) (along with automatic
“since”). That’s probably too science-fiction and I’m sure there are lots
of gotchas but just mentioning it here to make us dream a bit...
I don't see how what you are proposing is any different from the
Features documentation. Maybe this is the way to finally merge the
documentation instead of having it spread in e.x.o and RNs. I guess the
only difference is where we store the objects/pages. The release notes
presents information for a particular version, while feature documentation
presents information for a particular feature/category. We could use the
same objects, with different parameters to display both RN and
Documentation.
Regarding the inspiration for your proposal, I find their release notes
to be more interesting https://www.jetbrains.com/data
grip/whatsnew/#language-injections
For example they provide the "categories navigation" at the top and also
they group multiple functionalities for a particular category together,
using subheaders.
I like what you did with the prototype. Unfortunately it's a bit hard to
read and focus on reading the content: mostly because it's a bit crowded
(with the 2/3 columns layout) and the dark gallery background is very
distracting. But the styling can be fixed and the most important part are
the app and metadata.
The idea to present as note in the Miscellaneous section if it doesn't
have a screenshot is interesting. But we could also consider that we might
want to have some small category summaries, where we list just the text,
without any screenshots. Or that we might want to showcase just the
screenshots. But this are just small observations and can be improved with
display parameters.
Regarding importance, we need to be careful not to duplicate many things
that we have in the jira issue. A wild idea would be to assign per
functionality a jira issue and the app could extract metadata from there
(the importance, the category, the version, etc.) But that's SF :)
Nice work Vincent.
Thanks,
Caty
I’m starting to work on the POC. Let me know what you think.
Thanks
-Vincent
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs