Hi Marius;

> On 19 Sep 2016, at 13:46, Marius Dumitru Florea 
> <mariusdumitru.flo...@xwiki.com> wrote:
> On Sat, Sep 17, 2016 at 6:29 PM, Vincent Massol <vinc...@massol.net> wrote:
>> Hi again,
>> Done more coding (in front of the TV watching the Tennis David cup :
>> France vs Croatia ;))...
>> I’ve now completely rewritten the 8.3M1 release notes using the release
>> notes app:
>> https://www.evernote.com/l/AHc8Tp-XK6VMkY8ZL0YnNuEg7XLUavZliKM
>> FTR changes I’ve brought:
>> * In the end, "When the target audience is “developer” the screenshot is
>> replaced by an example.” was not a good idea and I’ve dropped it.
>> * For the developers section, I’ve used a single column view. FTR here’s
>> the wiki syntax for the New and Networthy part:
>> "
>> = New and Noteworthy (since XWiki 8.2) =
>> [[Full list of issues fixed and Dashboard for 8.3>>http://jira.xwiki.org/
>> secure/Dashboard.jspa?selectPageId=13629]].
>> == For Users ==
>> {{news columns="3" audience="user"/}}
>> == For Admins ==
>> {{news columns="3" audience="administrator"/}}
>> == For Developers ==
>> {{news columns="1" audience="developer"/}}
>> “
>> I’m quite happy about the result. Do you like it too?
> The release page layout should be responsive or at least it should look
> nice on a small screen. Hard-coding the 3-column layout is not nice.

I’m using bootstrap grids. We can tune that but it should already be responsive.

> The black background color of the gallery macro works when you have a
> single gallery, but in your case I feel it distracts the view.

The gallery should be a lot more configurable:
* Ability to set maxWdith/maxHeight
* Ability to set the background color
* Ability to not display navigation arrows and image number when there’s only 1 

> I assume you group the new features by category,

I don’t yet (but would be a good idea). I’m grouping by Audience only (user, 
admin, dev).

> but what about the order
> between the categories and inside each category. We want to push the most
> important features/categories first.

It’s a complex topic and I’m not sure sure we need it. The column layout I’ve 
shown allows to display a lot more changes than before. It’s also a change of 
spirit. The idea now is more that he release notes should focus on summarizing 
the changes rather than documenting them. It happens that we put too much in 
the release notes when the changes should be documented in the reference 
documentation. I think we only need a summary and then point to the reference 
documentation for more details.

What I mean is that I feel that the order is less important if the user can see 
at a glance all the changes in a more structured and visible way.

In addition the importance is relative. An item can be very important for a 
given release note but less important when put next to other changes from 
previous release notes. Said differently, if I ask for all changes from XWiki 
7.0 to XWiki 7.4, the importance order will definitely be different from the 
order for, say, XWiki 7.2.

So I’d say, let’s try without order first and see if we really need to define 
an order in the structure.

Now what we could do that would make sense I think is a global indication of 
the level of importance with 2 levels:
* High importance (new features, large improvements)
* Small importance (cosmetic changes, small improvements)

> Also, when there are many (small) new features it may be good to visually
> mark their category (or separate each category, like the headings we have
> know) because someone reading the release notes may be interested only in a
> specific topic (e.g. Solr changes).

That’s the point, the app allows you to generate a report of whatever you’re 
interested in. I dissociate 2 things:
* The Release Notes. Which is fixed and contains changes + other information 
(backward compat, translations, etc)
* The Changes App, which allows to generate all the changes from version N to 
version P, for category C, for target audience T. So you can ask: show me all 
changes in XWiki 8.3M1 related to Solr. In the future I’d like to add support 
for asking for specific tags too to be able to ask for all performance-related 
changes too. Note that the Category data could also be implemented in the same 
way I guess but FTM it’s implemented as an xproperty.

What we could do is display some tags displayed as labels under the change 

> Plus, it may be hard to understand from
> the title that a specific new feature is related to a specific topic
> (category), especially when you scan the release notes quickly in search
> for something (the Table of Contents is useful for this).
> +1 for adding more structure to the release notes.

Thanks for the feedback. There are plenty of things to do and tune. I want to 
get started.

Note: I also want to be careful about not adding too much structure since too 
much metadata means you need to fill it and we need to keep it easy to create 
Release notes.


> Thanks,
> Marius
>> Next step: Provide a UI for adding a release notes news (right now I’ve
>> used the object editor to write the RN for 8.3M1).
>> Thanks
>> -Vincent
>>> On 17 Sep 2016, at 12:27, Vincent Massol <vinc...@massol.net> wrote:
>>> I’ve done a quick POC locally, if you’re curious:
>>> * 3 columns view (using {{news columns=“3”/}}:
>>> https://www.evernote.com/l/AHcrwTDtWzBL7JaGLsTvj3NcP95dEYwraOc
>>> * 2 columns view (using {{news columns=“2"/}}:
>>> https://www.evernote.com/l/AHche7VWkv1KgLZPkWqbVv_ZGn728y-tAzw
>>> * Livetable view of data:
>>> https://www.evernote.com/l/AHcItOb57M9AMIaU6HXBTO04c3o91dVKck4
>>> Note1: I’ve added a title xproperty too.
>>> Note2: I’ve tweaked a bit the CSS of the galley macro but I could commit
>> this (see http://extensions.xwiki.org/xwiki/bin/view/Extension/
>> Gallery+Macro?viewer=comments#xwikicomment_6). I’ll also need to talk to
>> marius about the 128px padding for left/right arrows (which I’ve reduced to
>> 45px for the screenshots above).
>>> Thanks
>>> -Vincent
>>>> On 16 Sep 2016, at 18:18, Vincent Massol <vinc...@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/
>> datagrip/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’m starting to work on the POC. Let me know what you think.
>>>> Thanks
>>>> -Vincent

devs mailing list

Reply via email to