>>>>> On Wed, 19 Dec 2012 09:55:08 +0100, =?ISO-8859-15?Q?Michael_M=FCller?= <michael.mueller_at_mueller-bruehl.de> said:
MM> Hi volunteers,
MM> During my work, I have to writes specs, too. Not as big as th JSF one,
MM> just 30 to 100 pages each.
MM> In these prose docs, I write something like "if condition perform
MM> action1. Otherwise perform action2". Sometimes, when these condition get
MM> nested, complexity grows and it becomes hard to read. Then I like to
MM> switch to diagrams.
MM> In the spec, sometimes nested flows are described with indentation. This
MM> gives more clarity to the reader. But few descriptions growed so big,
MM> that they became complexe beasts, especially 7.4(.x) NagiagationHandler
MM> and 7.5 FlowHandler. Wouldn't it be helpfull to the reader, if we add
MM> diagrams like UML2 action diagram or simple old fashioned flow charts?
MM> Or is there a convention, only to use plain text?
There is no such convention, and there is no prohibition on diagrams.
Let me take that as an action item to improve the readability of the
navigationhandler algorithm section.
MM> In the prose spec there are a lot of references like "see JavaDoc of
MM> ...". But for some new "minor tickets" I couldn't find any reference
MM> within the prose spec. For example, I couldn't find a reference to HTML5
MM> friendly markup. Is there a special reason?
This is why I added the "Larger Changes" section to the preface, based
on the work that you and Ian did. If you think a feature needs an
overview in the PDF please let me know and I'll add it.
Ed
--
| edward.burns_at_oracle.com | office: +1 407 458 0017
| homepage: | http://ridingthecrest.com/