> On 19 Sep 2016, at 14:13, Ecaterina Moraru (Valica) <vali...@gmail.com> wrote:
[snip] >> 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. This is what I was saying above ;) Except that it’s not so easy and is a much bigger scope. What I propose is to start with the Release Notes application, and as data fills up, we can start experimenting with using it to generate reference documentation. I think the main issue we’ll have is that adding up changes doesn't generate good documentation. It only generates a randomly-ordered list of features with no narrative. In any case if we think it has value, we’ll be able to use it (and even possibly refactor the Release Notes app and extract a Features app from it). But let’s take it one step at a time! > The release notes presents information > for a particular version, while feature documentation presents information > for a particular feature/category. This is actually the same for both. They both present by category and version. For the reference documentation we use “Since XWiki N.NN” for the version info). > 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/datagrip/whatsnew/#language-injections I’ve refactored the app I started to support multiple displayer. I now have Grid + Flow. You choose the displayer as a macro parameter: {{changes … displayer=“flow” …/}} {{changes … displayer=“grid” …/}} > For example they provide the "categories navigation" at the top and also > they group multiple functionalities for a particular category together, > using subheaders. Don’t forget that currently our Release notes don’t present just Features (what I call Changes). They also present updated libs, tested stuff, translations, backward compat, etc). So in order to have a top nav as on the link you gave above, you’ll need to refactor the RN page and probably extract out the Changes part from it. Now I agree that for a user the main info are the Changes and we could change the design of our RN and focus on Changes and have a “Advanced” section at the end with the rest. This is where we’d need your help :) > 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. Yes, don’t worry you’ll have plenty of work to make it nice-looking ;) > 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. I’d really like to force having always screenshots for user-related changes. Anything too small to not have a screenshot is a misc for me. And I think we should do that since it would help us make sure that we always have screenshots for user-related changes. > Or that we might want to showcase just the screenshots. I don’t see how hard it is to add just a few words describing the screenshot. Note that since the screenshots are metadata if you want a report showing only screenshots that’s easy to do. > 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. Following Marius’s comment, I’ve added an “Importance” xproperty to the app (with 3 levels; High, Medium, Low). We’ll see how it goes. > 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 :) Yes and I’m not even sure it’s a good thing since JIRA is a tool to help development (the importance of an issue in jira doesn’t correspond to the importance a feature has for users). Thanks -Vincent > 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@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
