Documentation in Contrib

[Symon Rottem]

The new DocBook version of the Castle documentation is now available in the Contrib repository at:

http://svn.castleproject.org:8080/svn/castlecontrib/documenation

This initial checkin contains only the MonoRail DocBook source files in their initial, unedited state, NAnt build scripts to generate the output and the toolchain required to do the build. 

At this stage output generated includes single page HTML, multi-page HTML (one page per chapter) and a CHM file.  I anticipate the addition of PDF and VS 2005 add in documentation formats in the near future.

To build the documentation you will need to have a Java runtime installed, however you can easily use IKVM.NET as an alternative as long as you don't mind making some minor changes in the build files.  Each book can be built by executing NAnt against its build file (monorail.build for monorail, for example) or the whole tree can be built by using the default.build file.  Keep in mind that right now there are only MonoRail docs, so either way it's essentially the same thing.

Right now the content is only rudimentarily styled and only some code blocks have been syntax highlit - there are also likely to have been a couple of errors in transferring the data and several internal and external links are still broken. Since I have now got an initial buildable version in place I should be able to focus on fixing these and other content issues as well as continue work on migrating other frameworks in the Castle stack to the DocBook format.

Any feedback is welcome and comments or assistance with the state of the NAnt build scripts would be appreciated as this is my first try and I'm really just feeling my way around.

Enjoy.

--
Symon Rottem
http://blog.symbiotic-development.com

[Hamilton Verissimo]

I build it here locally without problems. Excellent work.

Before migrating the rest of the content, shall we agree on the
form/audience/wording? If we keep focused on MR docs for now, it would
be a much more manageable set to work with.

For instance, the documentation is much like an user guide. Will the
tutorials be migrated? What belongs to where? These are some of open
questions I have.

--
Cheers,
hamilton verissimo
ham...@castlestronghold.com
http://www.castlestronghold.com/

[Symon Rottem]

Agreed, I'd prefer to at least clean up the content for MonoRail before moving on to the next framework.

As for the tutorials, I don't know whether or not they belong in user guide style documentation but at the very least the location to the tutorials should be referenced from the docs.

Do you have a preferred style for form/audience/wording? 

I think the audience we should be targeting is the same as the one that would be using Microsoft products or Spring.NET - both professional developers and hobbyists alike.

Based on that I'm inclined to keep references to the second party (you, your) as the Spring.NET documenters have done.  I also think a dialogue style approach works well and prevents the content from being too dry - that can be reserved for API documentation.  The existing documentation has a good base there for this but could do with some expansion and grammatical corrections to improve the presentation for the aforementioned audience.

I'm certainly open to suggestions, however.

Cheers,

Symon.

[Hamilton Verissimo]

No preferences. I just want to set on something so I - and hopefully
others - can start contributing under some standard.

[Gauthier Segay]

Symon,

first, just to let you know that building the doc from the working
copy via nant was a bliss.

As for suggestion for MonoRail documentation, a first idea would be
visually identify which code sample pertains to controller code and to
view template code.

As well, it couldn't hurt if we were able to contribute such sample
translation: say c#/vb.net/... for controller's code, or nvelocity/
brail/aspview/... for view template code.

I think the end result should look similar to what exists in current
documentation:

http://www.castleproject.org/monorail/documentation/trunk/usersguide/res_localization.html

this kind of separation will also come for MicroKernel/Windsor where
it will be convenient to differentiate container configuration (being
written as xml/code/binsor) and container use in the code.

I don't know the way to perform that with good extensibility, I'm
unsure if embedding all the samples in the documents is the best way
or externalizing them is better.

Also for the core of the content, the best would be to get feedback
from new users, I'm pretty happy with "current" MonoRail
documentation; it helped me through the first steps and serve as good
reference when more advanced questions arise.

Thanks for your work!

On Mar 19, 12:49 am, "Symon Rottem" <s.rot...@gmail.com> wrote:
> Agreed, I'd prefer to at least clean up the content for MonoRail before
> moving on to the next framework.
>
> As for the tutorials, I don't know whether or not they belong in user guide
> style documentation but at the very least the location to the tutorials
> should be referenced from the docs.
>

> Do *you* have a preferred style for form/audience/wording?

>
> I think the audience we should be targeting is the same as the one that
> would be using Microsoft products or Spring.NET - both professional
> developers and hobbyists alike.
>
> Based on that I'm inclined to keep references to the second party (you,
> your) as the Spring.NET documenters have done.  I also think a dialogue
> style approach works well and prevents the content from being too dry - that
> can be reserved for API documentation.  The existing documentation has a
> good base there for this but could do with some expansion and grammatical
> corrections to improve the presentation for the aforementioned audience.
>
> I'm certainly open to suggestions, however.
>
> Cheers,
>
> Symon.
>
> On Wed, Mar 19, 2008 at 12:24 AM, Hamilton Verissimo <
>
>
>
> hamm...@castlestronghold.com> wrote:
>
> > I build it here locally without problems. Excellent work.
>
> > Before migrating the rest of the content, shall we agree on the
> > form/audience/wording? If we keep focused on MR docs for now, it would
> > be a much more manageable set to work with.
>
> > For instance, the documentation is much like an user guide. Will the
> > tutorials be migrated? What belongs to where? These are some of open
> > questions I have.
>

> > hamm...@castlestronghold.com
> >http://www.castlestronghold.com/
>
> --
> Symon Rottemhttp://blog.symbiotic-development.com

[Louis DeJardin]

Excellent! Thank you very much! Built on the second try (and the first
try made it clear htmlhelp was needed.)

Some of the push-back against monorail adoption we've received from
developers at our workplace has been about the perceived lack of
documentation and the loss of editor support when you move from
webforms to velocity. I've been very happy with the mix of online
information, brute force search of samples, and using reflector on the
libs, but I think this type of bundled material with organized table
of contents chapters and keyword search will help them hugely. I can't
wait to point them to it.

Along the subject of focus and migrating tutorials... The Getting
Started chapter reminds me of something I saw reading the rails book
(http://media.pragprog.com/titles/rails2/Contents.pdf) which was the
entire Part II section was a full blown walk-through of building an
entire functional web application from scratch. It introduced and
applied a new technology with each task - not to jump in to great
detail but just to the extent that it would be applied in a build-out.
I think each milestone had an "after" set of files to make it easier
to follow along.

I believe in the agile book the various web apps the excerpts came
from were available... yeah (http://www.pragprog.com/titles/rails2/
source_code)

Thanks again!
- Lou

On Mar 19, 12:59 am, Gauthier Segay <gauthier.se...@gmail.com> wrote:
> Symon,
>
> first, just to let you know that building the doc from the working
> copy via nant was a bliss.
>
> As for suggestion for MonoRail documentation, a first idea would be
> visually identify which code sample pertains to controller code and to
> view template code.
>
> As well, it couldn't hurt if we were able to contribute such sample
> translation: say c#/vb.net/... for controller's code, or nvelocity/
> brail/aspview/... for view template code.
>
> I think the end result should look similar to what exists in current
> documentation:
>

> http://www.castleproject.org/monorail/documentation/trunk/usersguide/...

[Symon Rottem]

Thanks Louis,

I'm not entirely sure of the best way to deal with multi language samples in the new docs, especially when we get to PDF versions, etc.  This is something that's been an issue I have been thinking about for a while, but haven't come up with a solution yet. Perhaps we could put them in separate callouts and have them referenced in an appendix?  Hmmm...

In the rails book you're referring to how did they present the samples?  Printed or in some kind of online resource?

Cheers,

Symon.

[Ken Egozi]

suggestion: online versions can have dhtml thing for languages, while the pdf version can be generated once per language. the problem is with pdf version explosions (server languages * view languages, if we'd take the commons it's VB+CS*NV+Brail+AspView = 6 versions) on the other hand, the process is not manual, so the creation of 6 pdf files shouldn't be a hassle. however a policy should be established about one changing a code sample in a certain language, should at least inform the ones who are maintaining the other languages so it would be kept in sync

--
Ken Egozi.
http://www.kenegozi.com/blog
http://www.musicglue.com
http://www.castleproject.org
http://www.mamaherb.com
http://www.gotfriends.co.il

[Symon Rottem]

Yeah, I can see the problem.  Honestly, I'm inclined to keep the documentation with a single programming language as you would find in most printed books but provide online resources where alternate versions of the code samples can be downloaded/viewed. 

The same system could be used in both the online and printed versions of the docs however the online version could use hyperlnks while the printed could just display the URLs explicitly.  I think having figure numbers on the code samples and providing URLs each language version of to the figure makes sense - maybe from an appendix?

If we take this approach the nice part is that I should be able to set up the DocBook source to reference external callouts for the content of each code sample which would make it easy to generate different versions or switch from one language to another in the future (as long as the code samples are kept up to date).

As for the languages to use, at this point I've stuck to C# for the controller/model code and NVelocity for view templates just to be consistent and because we already have samples in these languages for all sections.  If this should be changed someone should let me know.

As you said, however, some kind of policy for keeping sample versions in sync would be required.

Symon.

[Symon Rottem]

Although, all of that said, the idea Louis mentioned of just having a complete copy of the project the inline samples are taken from in other languages might be simpler than having separate language copies of each and every code sample.

Symon.