UserGuide needs a Reference Section

[activeeon-bot]

Original issue created by Fabien Viale on 29, Aug 2014 at 15:53 PM - DOC-217

---

There is a serious need for a stronger reference section. Which describes in detail all parameters of the JobWorkflow. The UserGuide works as a step-by-step tutorial and explaining general concepts, but the user is clueless whenever he needs detailed/exhaustive explanations and reference. For example how am I supposed to know what is a generation script and how can I use it ? An environment script ?

To illustrate the need, how could we hope to write Ant Jobs without the Ant XML reference book ? Had the reference book been missing, the Ant technology would never have been used !

[activeeon-bot]

Attachment:

• schedulerjob.html

[activeeon-bot]

Original comment posted by Youri Bonnaffe on 29, Aug 2014 at 16:04 PM

---

There is http://doc.activeeon.com/schedulerjob.html that is a representation of the XSD documentation (not very sexy but it is the best I could find).
IMHO we should use the XSD documentation tags to document that kind of things. It will be easier to maintain and keep consistent.

[activeeon-bot]

Original comment posted by Fabien Viale on 11, Sep 2014 at 19:09 PM

---

I found this online tool :
http://developpements.enc.sorbonne.fr/diple/demo/rng_html

It produces a quite good-looking doc I think (see file attached), the tool you found has the advantage to display XML bits, a shame that it looks so ugly !

[activeeon-bot]

Original comment posted by Youri Bonnaffe on 12, Sep 2014 at 08:51 AM

---

But it relies on RNG doesn't it? Because it looks a bit different to the XML format and it might confuse the reader.

[activeeon-bot]

Original comment posted by Fabien Viale on 12, Sep 2014 at 10:30 AM

---

yes it relies on relax-NG which is in the end our original schema (we translate this schema to XML-schema). I don't think the html produced is ideal, but it's better than the one produced with XML schema, it removes unnecessary printing of internal schema attributes which the user don't care about.

[activeeon-bot]

Original comment posted by Youri Bonnaffe on 12, Sep 2014 at 10:33 AM

---

what are the internal schema attributes here? http://doc.activeeon.com/schedulerjob.html#SchemaProperties
maybe we can remove some extra information

[activeeon-bot]

Original comment posted by Fabien Viale on 12, Sep 2014 at 11:26 AM

---

This can be removed :
Type Locally-defined complex type
Nillable no
Abstract no

The TOC can be removed too

And the red color should be replaced by the same light blue used in our documentation.

[activeeon-bot]

Original comment posted by Fabien Viale on 12, Sep 2014 at 11:32 AM

---

But then the problem is related to the structure of XML schemas. Instead of attributeGroup, it should be attribute, so the user can understand. And there should be a hierarchical view, so the user can understand that this attributes, refers to this element.

[activeeon-bot]

Original comment posted by Fabien Viale on 12, Sep 2014 at 11:34 AM

---

Or we could provide two links ? One with the XML-schema representation, and one with the relax-NG, so the user choose the representation he prefers ?

[activeeon-bot]

Original comment posted by Fabien Viale on 12, Sep 2014 at 11:35 AM

---

we'll need to document a bit better the schema before (it's too "concise")

[activeeon-bot]

Original comment posted by Youri Bonnaffe on 12, Sep 2014 at 11:38 AM

---

IMHO, we should provide only one (and possibly good...) representation, I dont find the RNG doc to be more readable (but I agree the XML one is a bit ugly).
I'm not convinced it is worth the effort too