[OOTB-addons] Documenting / organising acceptance criteria

Axel Faust axel.faust at prodyna.com
Fri Oct 31 10:05:13 GMT 2014


Hi Angel,

hmm – the wiki does not appear to have a decent comment / discussion support. Also, there are issues to consider regarding “frozen state/version” of acceptance criteria and working on content for a new iteration.
The wiki being a Git repo could theoretically help in some cases, but unfortunately the tooling is not that great – no ability to browse branches/tags in the wiki repo, no pull-requests …

For the moment, I would say:

-          Comments about the “how” / “why” of documenting / organizing our criteria belong in this discussion, e.g. anything about general structure, depth / detail and intent

-          Comments / discussion about specific contents in the wiki should have a separate “forum”

o   Option a) Spin off a new discussion on the mailing list

o   Option b) Create an issue with proposed change(s) and apply changes if in agreement (or no opposition after certain time)

o   Option c) Apply changes directly and

§  c1) use either option a) or b) to sort out conflicts with other people’s edits, or

§  c2) create “Talk”-pages (like in Wikipedia)

Use your own discretion about which option to choose based on the type of comment / issue you have with a piece of content.

Regards
Axel

Von: Ángel Borroy [mailto:angel.borroy at keensoft.es]
Gesendet: Freitag, 31. Oktober 2014 05:48
An: Axel Faust
Cc: ootb-addons at xtreamlab.net
Betreff: Re: [OOTB-addons] Documenting / organising acceptance criteria

Amazing job! I've been rewieving the content for a while, but I'll need further study in order to get all this map clear. However, I just have some comments on it. Should we use this mail list to discuss about it? Or is there any review mechanism on the wiki?

Best regards,
Angel

El domingo, 26 de octubre de 2014, Axel Faust <axel.faust at prodyna.com<mailto:axel.faust at prodyna.com>> escribió:
Hello all,

in the two weeks since Summit I have “played around” in our wiki (https://github.com/OrderOfTheBee/addons/wiki) trying out ways to document and organize any acceptance criteria we have for addons that we want to include in the collection. Currently, I have created a page for a “quick overview” of all criteria (https://github.com/OrderOfTheBee/addons/wiki/Inclusion-criteria-overview) and a couple of “sub-pages” that feature more detail in the description of requirements – and could potentially include examples of accepted vs. unaccepted constellations / behaviour in the future. These sub-pages are https://github.com/OrderOfTheBee/addons/wiki/Non-technical-inclusion-criteria and https://github.com/OrderOfTheBee/addons/wiki/Technical-inclusion-criteria for the moment, but may be further sub-divided when more content is included.

The overview should be easier to use as a checklist when we review any addons since you don’t have to interpret and mince with too much textual description. But I think we won’t get by without having a more detailed, descriptive version of the criteria catalog either as simple clarification or an argumentative basis when we discuss reviews with addon developers. If – in the long run – we engage with the Community in educating developers about aspects we consider “best practice”, this should allow us to easily expand a detailed description of a single rule / criterion into a dedicated HowTo / blog post.

The current content of these pages in regards to acceptance criteria reflects what I could think of to get started. Wherever possible I tried to keep the various comments from previous discussions in mind, but in the end, those contents are primarily intended as a plastic example.

Please take the time to review and share your thoughts.
As several people discussed at Summit, we need to keep the momentum of the Order in general going. I would like it if this meant we’ll have a first accepted draft of a criteria catalog sometime next month and start doing the first “prototype reviews” before Christmas holidays (and preparations) have everyone distracted for the rest of the year. Defining the “how” of criteria documentation is the first step…

Regards
Axel


--
Angel Borroy
keensoft
655 47 47 55
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.xtreamlab.net/pipermail/ootb-addons/attachments/20141031/7019b7e6/attachment-0001.html>


More information about the OOTB-addons mailing list