UserGuide needs a Reference Section #216
Comments
|
Attachment: |
|
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). |
|
Original comment posted by Fabien Viale on 11, Sep 2014 at 19:09 PM I found this online tool : 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 ! |
|
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. |
|
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. |
|
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 |
|
Original comment posted by Fabien Viale on 12, Sep 2014 at 11:26 AM This can be removed : The TOC can be removed too And the red color should be replaced by the same light blue used in our documentation. |
|
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. |
|
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 ? |
|
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") |
|
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). |
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 !
The text was updated successfully, but these errors were encountered: