Hi volunteers,
During my work, I have to writes specs, too. Not as big as th JSF one,
just 30 to 100 pages each.
In these prose docs, I write something like "if condition perform
action1. Otherwise perform action2". Sometimes, when these condition get
nested, complexity grows and it becomes hard to read. Then I like to
switch to diagrams.
In the spec, sometimes nested flows are described with indentation. This
gives more clarity to the reader. But few descriptions growed so big,
that they became complexe beasts, especially 7.4(.x) NagiagationHandler
and 7.5 FlowHandler. Wouldn't it be helpfull to the reader, if we add
diagrams like UML2 action diagram or simple old fashioned flow charts?
Or is there a convention, only to use plain text?
---
In the prose spec there are a lot of references like "see JavaDoc of
...". But for some new "minor tickets" I couldn't find any reference
within the prose spec. For example, I couldn't find a reference to HTML5
friendly markup. Is there a special reason?
--
Herzliche Grüße - Best Regards,
Michael Müller