[rules-dev] documentation

[Mark Proctor]

Geoffrey De Smet wrote:
> I am kinda favor in one big Drools "reference manual" (this is the 
> term coined by hibernate, spring and seam)
> It follows the structure you just outlined:
> - part expert
> - chapter 1 expert-intro
> - chapter 2 expert-foo
> - part flow
> - chapter 3 flow-intro
> - chapter 4 flow-bar
> - ...
The drools 4.0.x manual was already way too big and off putting for 
people, so it had to be reduced in one way or another. Basically if the 
manual is too big, people get lazy and end up bombarding the mailing 
lists or irc. The other reason is that we will be having people come 
from other disciplines, so someone coming from workflow does not want to 
be scared off by being bombarded rules information, so they need a book 
that comes from their angle, before easing into other points.
>
> The advantage of this that you can choose to view it as single_html 
> and use ctrl-F in firefox to find what you're looking for.
>
> The hibernate guys decided to separate the classic, annotations and 
> entitymanager:
> as a user I 've found this annoying, because I often find myself 
> having to ctrl-F on all single_html's before I find a solution (or I 
> realize it's not in the manuals).
>
> For example: I consulted the manual for
> "Does hibernate support a way to prefix all @Table names with "foo_"?"
> So I started in annotations, because of the @Table: nothing there.
> Next I looked in entitymanager, because it's general configuration: 
> nothing there.
> So hibernate doesn't support it.
> A few hours later I decided to check the hibernate classic manual too 
> - just in case - and I came across NamingStrategy, which does exactly 
> what I want...
Yes this is definitely a concern, we'll have to try and make sure we 
address that while writting it. However I think our case is slightly 
different there as hibernate annotations is an addon, where as 
drools-flow could be treated as a completely separate project and you 
can use it without ever having to know about rules.
>
> This one big book doesn't include the JBRMS "end user" manual of 
> course, that's a different audience.
>
> just my 2 cents :)
>
> Mark Proctor schreef:
>> Anyone using trunk documentation, be aware I'm doing a big refactor 
>> in the process of splitting up the documentation. Which is as follows
>> drools-docs-generaluserguide
>> drools-docs-expert
>> drools-docs-flow
>> drools-docs-fusion
>> drools-docs-guvnor
>> drools-docs-solver
>>
>> I'm struggling to what to call them, are they each "user guides". 
>> Drools Expert User Guide, Drools Flow User Guide. Or is it better to 
>> just hvae Drools Expert Docuementation, Drools Flow Documentation. 
>> Not sure. Also The User Guide is now just release notes, 
>> history/background info and general introduction, install guide. Its 
>> entitled Drools Introduction and General User Guide. That kinda 
>> sucks, anyone got a better name?
>>
>> I was going to split out documentation into it's own docbook modules, 
>> but as we have a separation of expert, flow and fusion I think it 
>> might get too fragmented. So I'll move examples docs back into the 
>> last chapter of each book. With the general splitting up it should be 
>> more manageable now having examples in the main project manuals.
>>
>> Mark
>> _______________________________________________
>> rules-dev mailing list
>> rules-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/rules-dev
>>
>
> _______________________________________________
> rules-dev mailing list
> rules-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/rules-dev
>