Feedback from the NHibernate guys

[James Gregory]

Hello everyone,

There's been a discussion taken place recently on the NHibernate developers mailing list that was in regard to which doc generation tool they're going to use with NHibernate. The winner hasn't been decided yet, but it seems to be weighing heavily towards DocProject. I'm not surprised or really even all that bothered by this decision, because Docu is a very new project. It would be improper of me to push Docu as a solution to their problems when it's barely alpha.

What has come out of their thread is an impressive comparision between Docu and DocProject. It would be foolish of us to pass this by, as it's a great opportunity to improve Docu based on some genuine real-world feedback.

I would suggest you read Stephen's post, but I would advocate that you don't reply over there as I've already been rude enough to weigh in on their voting process. I'll summarise his points below.

• Docu is flakey. It crashed numerous times and wasn't successfully used before modification of the code was required. This is a shame but not entirely surprising. We need more robustness.
• Docu is slow. This is to be taken with a grain of salt as DocProject performed equally; however, it's still damn slow. I think there are some key areas where we could utilise multiple threads to improve our processing speed (Assembly parsing should easily be able to be divided up, as could be the XML parsing, and possibly even the generation process itself).
• Docu style is not msdn. This is almost the point of docu, so I'm not entirely concerned by it; however, if we want wide acceptance a MSDN template may be worth creating.
• Docu doesn't generate CHM. Again, this is intentional; however, again, this is something we should maybe cater for.

I'd like to hear people's thoughts on what they make of these comments, and whether we should create some issues/set some goals based on it.

[Chris Missal]

My thoughts on:

• Flakey: How about running Docu against open source assemblies out there, to try to break it using actual, real code, instead of test assemblies. I've been running it on some code from my place of work, but unfortunately I'm not allowed to share this code.
• Slow: I like your multi-threading idea, but I think the previous bullet point should be tackled first.
• Not MSDN: I was thinking of adding a ticket for multiple/custom template choices. Right now, running docu.exe "file.xml" would use the default, but providing hooks to use some sort of template provider to determine which template should be used in the build. Building a CHM could tie in here too.
  

--
Chris Missal
http://chrismissal.lostechies.com/

[Jason Meridth]

• Docu is flakey. It's new
  
• Docu is slow. Optimization is later
  
• Docu style is not msdn. This is the point of Docu

I'm currently running against an APi for work and making changes as necessary.  Lots of local experimental branches.

---
Jason Meridth
http://jason.lostechies.com

[sbohlen]

Hey, everyone!

As the author of the aforementioned thread on the NH dev list, I'd
just like to weigh-in and encourage any readers of this thread to
please also read my post on the NH dev list.

I think James' summary of my Docu-related observations is generally
correct, but reading the summary here (without also reading my actual
comparative analysis in some detail) might unintentionally imply that
I was 'complaining' about Docu not being perfect, not producing MSDN-
style docs, or not being as 'mature' as something like DocProject when
nothing could be further from the truth; I like to think that I was
(or at least tried to be!) pretty even-handed in my comparative
analysis.

Later this evening (EDT) when I have a sec I will post some of the
details of some of the exceptions that I encountered when running
against the NHibernate.dll assembly so that hopefully this project can
benefit from my identification of some of the trouble-spots I
encountered in my testing.

For the record, I'm really impressed with this project's intent and
direction and absolutely wish it the best of luck -- I'll be watching
intently to keep myself appraised on its progress. I think its a
really neat idea with a bright future ahead of it!

Keep up the great work, guys~!

-Steve B.



On Mar 30, 1:27 pm, Jason Meridth <jmeri...@gmail.com> wrote:
>    - *Docu is flakey.* It's new
>    - *Docu is slow.* Optimization is later
>    - *Docu style is not msdn.* This is the point of Docu

>
> I'm currently running against an APi for work and making changes as
> necessary.  Lots of local experimental branches.
>
> ---

> Jason Meridthhttp://jason.lostechies.com
>
> On Mon, Mar 30, 2009 at 11:54 AM, Chris Missal <chris.mis...@gmail.com>wrote:
>
> > My thoughts on:
>
> >    - *Flakey:* How about running Docu against open source assemblies out

> >    there, to try to break it using actual, real code, instead of test
> >    assemblies. I've been running it on some code from my place of work, but
> >    unfortunately I'm not allowed to share this code.

> >    - *Slow:* I like your multi-threading idea, but I think the previous

> >    bullet point should be tackled first.

> >    - *Not MSDN:* I was thinking of adding a ticket for multiple/custom

> >    template choices. Right now, running docu.exe "file.xml" would use the
> >    default, but providing hooks to use some sort of template provider to
> >    determine which template should be used in the build. Building a CHM could
> >    tie in here too.
>

> > On Mon, Mar 30, 2009 at 11:42 AM, James Gregory <jagregory....@gmail.com>wrote:
>
> >> Hello everyone,
>

> >> There's been a discussion taken place<http://groups.google.com/group/nhibernate-development/browse_thread/t...>recently on the NHibernate developers mailing list that was in regard to

> >> which doc generation tool they're going to use with NHibernate. The winner
> >> hasn't been decided yet, but it seems to be weighing heavily towards
> >> DocProject. I'm not surprised or really even all that bothered by this
> >> decision, because Docu is a very new project. It would be improper of me to
> >> push Docu as a solution to their problems when it's barely alpha.
>
> >> What has come out of their thread is an impressive comparision between
> >> Docu and DocProject. It would be foolish of us to pass this by, as it's a
> >> great opportunity to improve Docu based on some genuine real-world feedback.
>
> >> I would suggest you read Stephen's post, but I would advocate that you
> >> don't reply over there as I've already been rude enough to weigh in on their
> >> voting process. I'll summarise his points below.
>

> >>    - *Docu is flakey.* It crashed numerous times and wasn't successfully

> >>    used before modification of the code was required. This is a shame but not
> >>    entirely surprising. We need more robustness.

> >>    - *Docu is slow.* This is to be taken with a grain of salt as

> >>    DocProject performed equally; however, it's still damn slow. I think there
> >>    are some key areas where we could utilise multiple threads to improve our
> >>    processing speed (Assembly parsing should easily be able to be divided up,
> >>    as could be the XML parsing, and possibly even the generation process
> >>    itself).

> >>    - *Docu style is not msdn.* This is almost the point of docu, so I'm

> >>    not entirely concerned by it; however, if we want wide acceptance a MSDN
> >>    template may be worth creating.

> >>    - *Docu doesn't generate CHM.* Again, this is intentional; however,

[James Gregory]

Hey Steve,

Sorry if my summary seemed to come across as negative, it wasn't intentional. Even if you were complaining, I wouldn't be concerned because all the points are perfectly valid. Docu isn't perfect, it doesn't produce MSDN style docs, and it is immature :) I think you did a good job of being objective.

Hearing where you encountered trouble would be very useful.

[James Gregory]

Chris & Jason:

Flakiness: The open-source tests sounds like a good idea. Currently I've tested it against FNH (obviously) and Rhino Mocks, but doing it against NHibernate sounds like a good idea, and the more the merrier.

Speed: Agreed that this isn't the highest of priorities, but however you slice it 15 minutes is slow; while I don't advocate premature optimisation, perhaps a casual run through dottrace wouldn't necessarily be premature at this point?

MSDN/Templates: Multi-template support is almost already available. All you do is point docu at a directory and it uses any templates in there. There's a hard-coded default to use "templates", but it can be changed. So to actually support multiple templates would just be a case of modifying the console app to provide some switches. As for msdn style itself, I can confidently say that as long as I'm the driver of Docu msdn will never be the default style. If somebody wants to contribute a template set for a msdn style, then I'm fine with distributing it, but it'll never be the default or recommendation.

I think there's a common misconception with a lot of developers that people prefer msdn style because that's what they're used to. I say that just because that's all that's available doesn't mean people actually like using it. All tools prior to Docu have only produced msdn style, so it's hard to really gauge anybody's opinions on alternatives. When it comes down to it, I think it's the content that matters. 

[Stephen Bohlen]

James:

 

No worries; I know your summary wasn't intended as negative -- I was only concerned that as some of the replies to the thread were starting to trend towards sounding defensive, I just wanted to reiterate that anyone reading this thread really should read my original post on the NH dev list.

 

Later tonight I'll post details of where I ran into troubles (perhaps on a new thread).

 

-Steve B.

--
Steve Bohlen
sbo...@gmail.com
http://blog.unhandled-exceptions.com
http://twitter.com/sbohlen

[Stephen Bohlen]

Re: the issue of MSDN-looking docs, I'd just like to mention that (for me at least) the issue I was trending towards with my point was actually less about the graphical style of the docs looking like MSDN content and more about the features, etc. that come with MSDN-style content.

 

As a simple example, consider just being able to search across the docs -- something supported under 'MSDN-style' docs and not (in its present alpha-state) supported by Docu.  This means that if I know (even sort of) where something is in Docu content I can probably browse to it, but if I want to search (for example) for the Map(...) method in FNH under Docu I have to know (or guess!) that its a method on the ClassMap class (and also know what namespace contains that class).  This might not be an issue with a smaller codebase, but certainly for something like NHibernate not having seachable content is a real impediment to being able to effectively use the reference docs.

 

As a more complicated example, consider the Visual Studio integration use-case; by integrating the content into a VS-compatible help file, users can place the cursor on a class or method, hit F1 and get the API reference to load for them pointed right to the desired topic.  Obviously a more complex use-case (and hardly mandatory as we all know what a perf slug the VS help system can be!), but since one of the recurring 'knocks' against OSS is 'poor documentation', anything that makes the documentation more approachable to new adopters is a net-plus IMHO.

 

Just some of my thoughts on the matter; I too am no lover of the graphics that come with the MSDN docs, but some of the features are at least desirable (if not mandatory) for interacting with a large set of reference documents with many namespaces, classes, methods, etc.

 

Again, just my 2-cents; hope this helps clarify (a bit) where I was coming from on this one point.

 

Keep up the great work~!

 

-Steve B.

http://twitter.com/sbohlen

[James Gregory]

That I can agree with :) I've actually been toying with a Javascript-only search implementation using a JSON generated index at "compile" time. It seems to work pretty well but it's fundamentally tied to browser perf (aka it means IE is pretty sluggish). The problem with search is always going to be keeping dependencies small. I can certainly agree with the need though.

As for VS integration, I can see your point but I've never known anyone to actually use the VS builtin help. I know it sounds like exaggeration, but I've honestly never seen a single developer use it. What I have seen (or rather heard) is the groans of when someone accidently hits F1 and the "Hang on while I index for 10 minutes" dialog pops up... :) Still, point taken.

Thanks for the clarification.

[Jason Meridth]

James & Steve:

My response earlier was too concise and I can see how it could be misconstrued as close-minded.  This project is James' idea.  I agree with James' notes that he mentions to Chris and I.  I will be reading the post on the NHib dev list.

Any information/feedback is good.  Thanks Steve for giving ideas.

Sincerely,
---
Jason Meridth
http://jason.lostechies.com

[sbohlen]

Jason:

No offense taken (intended or otherwise!).

Some of the (sadly) limiting aspects of typed text as a communication
medium are that sarcasm transmits poorly, brevity in the interests of
efficiency can be interpreted as brushing someone off, and its all-too-
easy for things to get completely misinterpreted even surrounded by
1000 words for context.

My reiteration that I wasn't being overly-critical of the Docu team's
efforts, direction, output, whatever was just an attempt to try to
ensure that my point of view was being taken in the spirit intended.
I've had all-too-many internet-based discussions spiral out of control
and lead to personal invective due to just these kinds of
misunderstandings and so I'm perhaps ultra-sensitive to trying to
reframe my positions clearly whenever there is even a whiff of a
potential misunderstanding taking root (real or imagined on my part
<g>).

No offense taken (as you say, none was intended).

I hope my input has helped even in some small way with the efforts the
Docu Team is undertaking to develop this thing.

-Steve B.

On Mar 30, 10:55 pm, Jason Meridth <jmeri...@gmail.com> wrote:
> James & Steve:
>
> My response earlier was too concise and I can see how it could be
> misconstrued as close-minded.  This project is James' idea.  I agree with
> James' notes that he mentions to Chris and I.  I will be reading the post on
> the NHib dev list.
>
> Any information/feedback is good.  Thanks Steve for giving ideas.
>
> Sincerely,
> ---

> Jason Meridthhttp://jason.lostechies.com

>
> On Mon, Mar 30, 2009 at 5:28 PM, James Gregory <jagregory....@gmail.com>wrote:
>
> > That I can agree with :) I've actually been toying with a Javascript-only
> > search implementation using a JSON generated index at "compile" time. It
> > seems to work pretty well but it's fundamentally tied to browser perf (aka
> > it means IE is pretty sluggish). The problem with search is always going to
> > be keeping dependencies small. I can certainly agree with the need though.
> > As for VS integration, I can see your point but I've never known anyone to
> > actually use the VS builtin help. I know it sounds like exaggeration, but
> > I've honestly never seen a single developer use it. What I have seen (or
> > rather heard) is the groans of when someone accidently hits F1 and the "Hang
> > on while I index for 10 minutes" dialog pops up... :) Still, point taken.
>
> > Thanks for the clarification.
>

> >> On Mon, Mar 30, 2009 at 5:22 PM, James Gregory <jagregory....@gmail.com>wrote:
>
> >>> Chris & Jason:
> >>> *Flakiness:* The open-source tests sounds like a good idea. Currently

> >>> I've tested it against FNH (obviously) and Rhino Mocks, but doing it against
> >>> NHibernate sounds like a good idea, and the more the merrier.
>

> >>> *Speed:* Agreed that this isn't the highest of priorities, but however
> >>> you slice it 15 minutes is *slow*; while I don't advocate premature

> >>> optimisation, perhaps a casual run through dottrace wouldn't necessarily be
> >>> premature at this point?
>

> >>> *MSDN/Templates:* Multi-template support is almost already available.

> >>> All you do is point docu at a directory and it uses any templates in there.
> >>> There's a hard-coded default to use "templates", but it can be changed. So
> >>> to actually support multiple templates would just be a case of modifying the
> >>> console app to provide some switches. As for msdn style itself, I can

> >>> confidently say that as long as I'm the driver of Docu msdn will *never* be

> >>> the default style. If somebody wants to contribute a template set for a msdn
> >>> style, then I'm fine with distributing it, but it'll never be the default or
> >>> recommendation.
>
> >>> I think there's a common misconception with a lot of developers that
> >>> people prefer msdn style because that's what they're used to. I say that
> >>> just because that's all that's available doesn't mean people actually like

> >>> using it. All tools prior to Docu have *only* produced msdn style, so

> >>> it's hard to really gauge anybody's opinions on alternatives. When it comes
> >>> down to it, I think it's the content that matters.
>

> >>> On Mon, Mar 30, 2009 at 9:08 PM, James Gregory <jagregory....@gmail.com>wrote:
>
> >>>> Hey Steve,
> >>>> Sorry if my summary seemed to come across as negative, it wasn't
> >>>> intentional. Even if you were complaining, I wouldn't be concerned because
> >>>> all the points are perfectly valid. Docu isn't perfect, it doesn't produce
> >>>> MSDN style docs, and it is immature :) I think you did a good job of being
> >>>> objective.
>
> >>>> Hearing where you encountered trouble would be very useful.
>

> ...
>
> read more »

[Jason Meridth]

Your feedback is AWESOME.

Thank you for the help bro.

---
Jason Meridth
http://jason.lostechies.com