Documentation

[Symon Rottem]

I know there have been plenty of discussions, complaints and all out
rants regarding the state of the documentation for the castle project.
I have my own two cents to add to the discussion.

Recently I've been trying to get a team of new users up and running
using MonoRail with Windsor integration and it's been an uphill
battle. Although there is actually quite a lot of documentation it's
not organized in a cohesive manner and frequently there may be
sufficient documentation about a feature but it can't be found
easily.

The feedback from the team (and my own observation) is primarily that
a) the documentation, while not exatctly lacking, could benefit from
more detailed explanations in addition to the plentiful code examples
and b) they felt that having a user guide presented more like a book
(the documentation for Sping.NET was cited as a specific example)
would have helped them to get up an running faster.

Personally, I believe that this can be remedied fairly easily but
would require restructuring the presentation of the information into a
hierarchical series of nested sections so that the documentation could
be re-presented. The structure needs a clear table of contents that
shows an overview of the hierarchy and should be fully hyperlinked. In
addition, it would be useful to be able to obtain an offline copy of
this information in another format which can optionally be printed -
to my mind that means PDF.

Now, before anyone goes and shoots me down (and I *have* seen some
pretty insensitive posts when people raise issues with the
documentation, so I'm almost expecting it), I'm specifically
contributing this feedback because I'd like to put my money where my
mouth is and actually do something about it. I have had some
experience with authoring technical documentation in the past and
would at the very least like to look a restructuring the presentation
of the existing info.

I have some thoughts about how this should be done - migrating to
DocBook format for the XML and generating documentation more in line
with that presented by the Spring.NET crowd for a start - but I don't
want to wade in and start making changes without some feedback first
since I don't want my efforts to be wasted. Certainly I could just
dive in and start but if my proposed changes are not considered
acceptable by the community at large my contribution will become stale
pretty quickly.

So...any thoughts or suggestions?

Symon.

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

[Symon Rottem]

Oh, and I should point out that I'm specifically discussing the
Getting Started and User Guide style of documentation here, not the
API docs. The API documentation is quite well presented at the moment
but could probably benefit from more explanatory remarks for the
classes members and namespaces. Again, I'm happy to help out on those
too.

[Gianluca Gravina]

Symon, I totally agree with you.

We have at the moment four main documentation entry points:
1) getting started section in castleproject website
2) using wiki in castleproject website
3) castle forum
4) "this" devel list.

I know it isn't easy to stop brains working and "refactoring" what we've
done to write down a comprehensive documentation to give newbies an
interesting lecture about our work. But I think it's mandatory in order to
wave the work and make the "users" community grow.

I think Spring.NET pdf and NHIbernate pdf are example comprehensive enough
to explain what I'm trying to figure out.

We recently deployed a part of a website with castle monorail + Windsor
container + Nhibernate. Well it's been so cool working with those framework
I'm trying to push it here in Italy in our MiniConf (http://www.ugialt.net),
but the answer I get while making a diff between Monorail and Asp.NET Mvc
it's always "Lack of documentation", and this lack will bring Monorail
buried from Asp.NET MVC. And it's a pity, but i Agree ...

For some specific kind of core functionality there's only tailor's made
solutions with code investigation and reflector giving a huge help.

But ... I have to say that it's a huge and great work you made, and I
appreciate it very much.

Many compliments !

Gianluca Gravina
http://bogs.ugidotnet.org/thinkingingrava

[Ayende Rahien]

Symon,
Anyone who wants to work on the documentation is always welcome.
Right now the docs are using the Anakrina (sp?) styles to handle that. It is probably possible to have something that would convert them to doc book. I am more in favor of having that step automated, because this way we can get it to the web site and to PDF more easily. Than having the doc book styles on the web.

[Colin Ramsay]

I agree with this, but I wonder if there is a "best time" to do
documentation? If there is a new release coming soon, does it make
sense to make a big documentation push based on the last release?
IMHO, if Symon is going to put effort into this (and I know everyone
would appreciate it if he did) then I think it may be best to find out
when the next release is anticipated.

[Ayende Rahien]

I don't think that there is a bad time to work on documentation.
Certainly before a release we should put more effort into it, but I don't see the relation

[Colin Ramsay]

Hmm. What I mean is that if effort gets put into making documentation
for feature xxx and then that feature gets removed or heavily changed
in the next release, then the effort in documenting it isn't being
used as efficiently as it could have been.

However, I think that for the most part (particularly with general
guides and tutorials) this isn't too much of concern.

[Hamilton Verissimo]

On 3/1/08, Gianluca Gravina <gianluca...@gmail.com> wrote:
> but the answer I get while making a diff between Monorail and Asp.NET Mvc
> it's always "Lack of documentation", and this lack will bring Monorail
> buried from Asp.NET MVC. And it's a pity, but i Agree ...

Huh? The ASP.Net MVC, aside from some blog posts has zero
documentation. I dont get this argument.

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

[Hamilton Verissimo]

Another thing that we have to decide is if we want a pdf/SVN book
style, or we want a MSDN style documentation. I couldn't care less,
but I remember some discussion towards the MSDN style...

On 3/1/08, Symon Rottem <s.ro...@gmail.com> wrote:
>

[Ayende Rahien]

API docs - MSDN style
Anything else - book style.

[Hamilton Verissimo]

I'm not sure that was the outcome. I remember suggesting glueing it
altogether using Sandcastle. There are some place holders at
http://svn.castleproject.org:8080/svn/castle/trunk/docs/

I find it pretty standard for the MS world. Unity also comes with this
style of documentation.

On 3/1/08, Ayende Rahien <aye...@ayende.com> wrote:

[Gianluca Gravina]

Yep, now it's as you said, but for the future, I think it will be painful
commented and documented, I get your point, and I agree with you, But get
real, the CTP has been released in December (If i remember well) and nowaday
we've got only forums and some blog posts as you said. Manning is publishing
a Book on Asp.NET mvc, the MS-Community it's still pushing hard on the MVC
pattern (finally).

Hamilton, I love Monorail, as I love Nhibernate, but I see some kind of
difference between:
- Asp.NET MVC vs Monorail
- Entity Framework vs Nhibernate
... and it isn't a good metric in order to measure documentation on some
kind of project, but results querying google with "asp.net mvc" and "castle
monorail" are quite different.

Don't misunderstand me, I'm still pushing on Monorail ... I'm still having
fun with it ... and I'd like to continue to use it !!! People like you,
Ayende and many others have pointed my way of facing design problems.

Perhaps I'm totally wrong and Monorail will keep rocking even with Asp.NET
mvc release. I hope !

Have a nice weekend.

Sincerly, Gianluca

[Symon Rottem]

Ayende,

The documentation for Spring.NET is in DocBook format and is simply
run through two different processes to generate the online
documentation and the PDF along with other formats such as CHM and VS
documentation.

I believe they do it all from NAnt scripts using different DocBook XSL
stylesheets that output appropriate data. For the web they use an
XSLT that generates XHTML, for PDF an XSLT that generates FO data
that's run through Apache FOP to create the PDFs. I assume we could
do the same.

Cheers,

Symon.

On Mar 1, 4:04 pm, "Ayende Rahien" <aye...@ayende.com> wrote:
> Symon,
> Anyone who wants to work on the documentation is always welcome.
> Right now the docs are using the Anakrina (sp?) styles to handle that. It is
> probably possible to have something that would convert them to doc book. I
> am more in favor of having that step automated, because this way we can get
> it to the web site and to PDF more easily. Than having the doc book styles
> on the web.
>

[Hamilton Verissimo]

On 3/1/08, Gianluca Gravina <gianluca...@gmail.com> wrote:
> Yep, now it's as you said, but for the future, I think it will be painful
> commented and documented, I get your point, and I agree with you, But get
> real, the CTP has been released in December (If i remember well) and nowaday
> we've got only forums and some blog posts as you said. Manning is publishing
> a Book on Asp.NET mvc, the MS-Community it's still pushing hard on the MVC
> pattern (finally).

That still a weird argument. I relies on something that is not concrete.

MonoRail is going to die if, and only if, MS MVC is so fantastic that
even I wont find a good reason to still using MonoRail. Is that a safe
bet? I dont know. It's hard to tell. I'm inclined to think that wont
be the case. MR will still be a good option for more hardcore
developer.

If you team/friends/groups would rather pick MS MVC because of the
lack of MR documentation, I guess that's just a handy excuse. Nothing
more than that.

[Symon Rottem]

I'm with Ayende:

API docs - MSDN style
Anything else - book style.

API documentation needs to be highly searchable, indexed and
hyperlinked otherwise it's close to useless. The existing
presentation of the API documents is more than good enough although it
might be useful to have an index along with the table of contents and
allow searching...but that's another story and something I would
consider a much lower priority. Anyway, my current focus would be
directed more to the reference/user guide rather than the API
documents.

See these links on the Spring.NET site for a guide to how I would like
to approach presenting the Castle docs:

HTML Reference Manual: http://www.springframework.net/doc-latest/reference/html/index.html
PDF Reference Manual: http://www.springframework.net/doc-latest/reference/pdf/spring-net-reference.pdf
API Documentation: http://www.springframework.net/docs/1.1/sdk/2.0/html/webframe.html
(Castle's current API Doc format is already basically the same)

Conversion of the existing reference XML files to DocBook will be
relatively trivial - I'll roll a quick XSL to transform the existing
XML content to match the DocBook DTD and then I can start cutting up
the existing files to reorganize them into a format I think will be a
little more coherent. Obviously style is something that can be added
during or after the restructuring and the result need not look exactly
like the Spring.NET docs.

Thoughts?

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

On Mar 1, 5:47 pm, "Ayende Rahien" <aye...@ayende.com> wrote:
> API docs - MSDN style
> Anything else - book style.
>

> On 3/1/08, Hamilton Verissimo <hamm...@castlestronghold.com> wrote:
>
>
>
> > Another thing that we have to decide is if we want a pdf/SVN book
> > style, or we want a MSDN style documentation. I couldn't care less,
> > but I remember some discussion towards the MSDN style...
>

> > hamm...@castlestronghold.com
>
> >http://www.castlestronghold.com/

[Hamilton Verissimo]

Sounds like a plan. Thanks for the effort.

On 3/1/08, Symon Rottem <s.ro...@gmail.com> wrote:
>

[grava]

Hamilton, it's not about me, my group and my friends ... I repeat
myself, I used Monorail for a "already deployed in production"
project.

I only hope you're right, and it's not only a point of view of a
"fantastic" person in a world much different from "fantastic".

Again, hope you're right !

bye,

Gianluca

On Mar 1, 6:37 pm, "Hamilton Verissimo" <hamm...@castlestronghold.com>
wrote:

> hamm...@castlestronghold.comhttp://www.castlestronghold.com/

[Symon Rottem]

Quick additional question - would people prefer to see one large html
tree/PDF that encompasses *all* the Castle documentation or would it
be better to generate separate books for each technology? In other
words we could have a Castle Reference Manual or we could have a
MonoRail Reference Manual, a Windsor/Micro Kernel Reference Manual,
etc.

Spring appear to have taken the approach of a single document
encompassing all technologies in their stack and you can jump to
subsections that deal with a particular technology.

Anyone have any thoughts?

[Ayende Rahien]

No preference from my part.

[alwin]

I like one big TOC with all the technologies, that way you see all the
possibilities faster i think.
There is also overlap between technologies, for example MR - AR and MR
- IoC.

How will the wiki (using section) integrate with the new docs?
Maybe the official docs can have links to the appropiate wiki spaces?
Those links are there now, but there could be more.
I think that the wiki is a bit underused and hard to discover. "Is
there a wiki? I never knew that." That's a pity because it has big
potential.
Recently i'm trying to put links on the wiki for Castle-related blog
posts etc that i find on the web.

And how do projects that Castle uses (e.g. NHibernate), or projects
that are built upon Castle (for example rhino commons) fit into all
this?
Links to those projects, or relevant documentation (NH chapters etc)
are very useful.

It's a great plan Symon!

[Symon Rottem]

We should probably have a single documentation page on the website that provides links to the reference documentation, the wiki and the API docs but my inclination is to keep the content in the wiki separate from the documentation itself which would be more official.

I would anticipate that periodically the information from the wiki would be used by those maintaining the documentation as a source from which clues about what needs to change could be harvested when the next set of updates are to be performed.  That said, the wiki should stand nicely on it's own.

At this stage I haven't really considered how the new docs will be integrated into the existing website and I'm hesitant to make any modifications without hammett's blessing.  There are a lot of points where the existing documentation is referenced so the website would undergo quite a few changes if we take the approach I've outlined above.

In the meantime I'll just keep working on reorganizing the existing docs.

Symon.

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

[Symon Rottem]

Looking though the site source I can't seem to find any documentation on DynamicProxy.  I was planning on adding it to the documentation tree but the only page I could find relating to it is here: http://www.castleproject.org/dynamicproxy/index.html

Am I missing something?

Cheers,

Symon.

[Hamilton Verissimo]

You're not. I never found the time to migrate the old documentation
(which btw wasnt very good)

On 3/3/08, Symon Rottem <s.ro...@gmail.com> wrote:

[Ayende Rahien]

Yes, the underlying assumption that by the time you are done understanding DP you don't have the strength to write docs.

On 3/3/08, Symon Rottem <s.ro...@gmail.com> wrote:

[Hamilton Verissimo]

:-)

On 3/3/08, Ayende Rahien <aye...@ayende.com> wrote:
> Yes, the underlying assumption that by the time you are done understanding
> DP you don't have the strength to write docs.

--

[Symon Rottem]

Hamilton,

Is there somewhere I can find the old docs so I can use them as a starting point?  I feel strong enough...for the moment! :)

Cheers,

Symon.

[Markus Zywitza]

Symon,

can you please share your current efforts, probably as a castle contrib project.

Background: The documentation discussions pop up around every two to
three weeks. However, most of the people that complained so far, were
not willing to contribute.
After the last discussion I had the idea to use NHibernate's reference
docs (also docbook) as a template and see what documentation could be
compiled into a Castle guide or something. But I stumbled over my
hitherto nonexisting knowledge of docbook, so I didn't get far enough
to make a call to this list.
So if you managed to create the proper environment for a Castle
docbook documentation and perhaps even already transformed some
existing docs, I'd be happy to fall in and help you updating and
correcting content, so that the docs reflect the current trunk (I
think they got outdated esp. for MR).

-Markus

[Symon Rottem]

Markus,

 

There's nothing I can provide yet - only fragments from an automated conversion that are not yet fit for human consumption.  I should have the data restructured in the next few days and will post it so people can comment before I begin refactoring the content. 

 

The other part that still needs to be worked out is the automation of the transformation from DocBook format to HTML and PDF.  I've got a friend here in France helping me with that, so we should see something soon.

 

I'll post on my blog and back here when there's something to see.

 

Symon.

[Markus Zywitza]

Symon,

as I already said, NHibernate got that structure including NAnt build
files for free (LGPL). It has minor issues (no graphical bullets,
problems with callouts etc.) but overall it works with small friction.

I can send you the zipped folder if you like (it's about 3MB large, so
I won't send it to the list).

[Symon Rottem]

Thanks Markus,

That'd be great.  We're also looking at how Spring.NET have handled it but it would be handy to compare the approaches.

 

Cheers,

 

Symon.

[Symon Rottem]

Markus,

I didn't fully respond to your earlier message:

I'd love some assistance with content refactoring once I've restructured the documentation.  I'll keep you posted and provide you with a copy of the DocBook files once they're together.

And thanks for your existing package - I'll take a look at it tonight.

[Symon Rottem]

Hmm.  After some deliberation I think we're going to have to provide separate documentation for each framework since they're not all released on the same schedule.  Is there any likelihood that this will change?  Otherwise docs for MR should be separate from Windsor, etc.

We should still have all versions of the documentation for all frameworks available through a single entry point though. 

[Markus Zywitza]

They have different version numbers, but AFAIR there never has been a
release of only a single part of Castle, there were just complete RCs.
I don't think that this will change, but the last word has Hamilton.

-Markus

[Symon Rottem]

Below is a proposed structure for the MonoRail documentation (RC2 for
this version):

1. Introduction
1.1. Overview
1.2. Background
1.2.1. What is MVC
1.2.2. Convention Over Configuration
1.3. Why Use MonoRail
1.4. How It Works
1.5. Licence Information
1.6. Support
2. Getting Started
2.1. Requirements
2.2. Creating the Project Skeleton
2.2.1. Using the MonoRail Project Wizard
2.2.2. Creating the Project Manually
2.3. Controllers and Views
2.3.1. Your First Controller and View
2.3.2. Setting the Layout and Resuce
2.3.3. Creating the Index View and Action
2.3.4. Creating the Layout
2.3.5. Seeing the Results
2.3.6. Passing Values to the View
2.3.7. Creating a Rescue
2.4. Data Binding
2.4.1. Simple Parameters
2.4.2. Complex Objects
2.5. Integrating with ActiveRecord
2.5.1. Adding Assemblies
2.5.2. Configuration
2.5.3. Building the Model
2.5.4. Initializing the Handler
2.5.5. ActiveRecord Sacffolding
2.5.6. Creating a CRUD Page Using DataBind
2.6. Final Comments
3. Installation
3.1. Running Under IIS
3.2. Usin Casini
3.3. Mono with XSP
3.4. Mono with Apache
3.4.1. Configuration
3.4.2. Apache Httpd2
3.4.3. Application Deployment
3.5. Deploying to a Shared Host
4. Configuration
4.1. Formal Definition
5. Controllers
5.1. Naming Convention
5.2. Areas
5.3. Actions
5.3.1. Default Action
5.4. Redirecting
5.5. Data Binding
5.5.1. The SmartDispatchController
5.5.2. Other Useful Properties
5.5.3. Simple Parameter Binding
5.5.4. Custom Binding
5.6. Wizards
5.6.1. Wizard Controllers
5.6.2. Wizard Action Provider
5.6.3. Steps
5.6.4. Nested Actions
5.6.5. DoNavigate
5.6.6. Conditional Steps
5.6.7. The WizardHelper
5.6.8. Windsor Integration
6. Views
6.1. Folder Structure Convention
6.2. Selecting a View to Render
6.3. Passing Values to a View
6.3.1. The PropertyBag
6.3.2. Flash
6.4. Shared Views
6.5. Cancelling a View
6.6. Accessing Values Passed by the Controller
6.7. View Engines
6.8. Javascript and Ajax
7. View Components
7.1. Creating a View Component
7.2. Using View Components
7.3. Passing Parameters
7.4. Block and Nested Sections
7.5. Built In View Components
7.5.1. CaptureFor
7.5.2. SecurityComponent
8. Filters
8.1. Creating a Filter
8.2. Ordering
8.3. Skipping Filters
8.4. Passing Parameters
8.5. Creating
9. Layouts
10. Rescues
11. Authentication and Authorization
11.1. Forms Authentication
11.2. Filters
11.3. Using PrincipalPermission
11.4. The SecurityView Component
12. Resources and Localization
12.1. Using Resources
12.2. Setting Up the Current Culure
12.3. Localization
13. Sending Email
14. Unit Testing
14.1. The TestSupport Assembly
14.2. Exposing the Website Application Directory
14.2.1. Overriding GetPhysicalDir
14.2.2. External Configuration
15. Integrations
15.1. ActiveRecord
15.1.1. Scaffolding
15.2. Windsor Container
16. Advanced Topics
16.1. Routing
16.1.1. Routing
16.1.2. Root Directory Mapping Workaround
16.2. Dynamic Actions
16.2.1. Dynamic Action Providers
16.3. Scaffolding
16.4. Extensions
16.4.1. Custom Session Extension
16.4.2. Exception Chaining Extension
16.4.3. Creating Your Own Extensions
16.5. Service Architecture
16.6. Custom Bindable Parameters
16.7. Using Resources to Store Views

If anyone has any feedback I'd love to hear it.

Further information is available in this blog post:
http://blog.symbiotic-development.com/2008/03/07/documenting-castle-proposed-structure/

Unless there's any major objections I will follow the same approach
for the other frameworks.

Symon.

[Gianluca Gravina]

Seems to cover more or less all of the main areas useful for a first dive
with Monorail.

Many compliments Symon.

Gianluca

[Patrick Steele]

Looks great! Thanks for working on this.

Should section 3 (Installation) come before 2 (Getting Started)?
Isn't the first step in getting started with any framework the
installation?

Also, are 8.1 and 8.5 the same tring?

Can't wait to see this come together! I'm pretty busy right now, but
I'll try and lend a hand when possible.

[Symon Rottem]

I'll take a look, but the reason for the current order is that the first few steps of the Getting Started section deal with setting up your development environment so it's lightly covered there while the Installation section deals with setting up a server in more detail.  Perhaps Installation should be broken up into a simple getting started section and move more detailed server setup stuff to Advanced Topics?  I'll see what I can do.

 

Symon.

[Symon Rottem]

And yes - 8.5 is a typo.

http://blog.symbiotic-development.com

[Erik Dahlstrand]

Awesome! How about a section on validation support?

I'm not a native English speaker but if there is anything else I can
do to help, don't hesitate to ask.

/Erik

On 7 Mar, 16:35, "Symon Rottem" <s.rot...@gmail.com> wrote:
> And yes - 8.5 is a typo.
>
>
>
> On Fri, Mar 7, 2008 at 4:34 PM, Symon Rottem <s.rot...@gmail.com> wrote:
> > I'll take a look, but the reason for the current order is that the first
> > few steps of the Getting Started section deal with setting up your
> > development environment so it's lightly covered there while the Installation
> > section deals with setting up a server in more detail. Perhaps Installation
> > should be broken up into a simple getting started section and move more
> > detailed server setup stuff to Advanced Topics? I'll see what I can do.
>
> > Symon.
>

> > On Fri, Mar 7, 2008 at 3:02 PM, Patrick Steele <patrick.ste...@gmail.com>

> > wrote:
>
> > > Looks great! Thanks for working on this.
>
> > > Should section 3 (Installation) come before 2 (Getting Started)?
> > > Isn't the first step in getting started with any framework the
> > > installation?
>
> > > Also, are 8.1 and 8.5 the same tring?
>
> > > Can't wait to see this come together! I'm pretty busy right now, but
> > > I'll try and lend a hand when possible.
>

> > > On Fri, Mar 7, 2008 at 8:29 AM, Symon Rottem <s.rot...@gmail.com> wrote:
>
> > > > Below is a proposed structure for the MonoRail documentation (RC2 for
> > > > this version):
>

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

> --
> Symon Rottemhttp://blog.symbiotic-development.com

[Symon Rottem]

Huh - somehow the entire chapter about helpers fell out of my tree.  The chapter will fall between "Authentication and Authorization" and "Resources and Localization" and, for the moment, will be structured as follows:

12. Helpers
    12.1. Built In Helpers
        12.1.1. AjaxHelper
        12.1.2. DateFormatHelper
        12.1.3. Effects2Helper
        12.1.4. FormHelper
        12.1.5. HtmlHelper
        12.1.6. PaginationHelper
        12.1.7. ValidationHelper
        12.1.8. WizardHelper

You'll see the section on the ValidationHelper in there, but that's about all I have for now. 

If you've got any existing information on validation, code samples or anything - it doesn't matter whether or not it's written in perfect english (I can happily edit the language if the information makes sense) - I can try to find somewhere it fits into the docs, so send it in. 

All submissions are welcome - although I can't promise I'll use everything submitted in the initial round, once the new version is in the wild (and has been accepted by the SVN committers) people can edit and submit patches like any other piece of code.

Cheers,

Symon.

[Hamilton Verissimo]

I`d suggest:

> 12. Helpers
12.1 Creating a helper
12.2 Using a helper
> 12.3. Built In Helpers
12.1.1. UrlHelper
> 12.1.2. FormHelper
> 12.1.3. AjaxHelper
> 12.1.4. PaginationHelper
12.1.5. TextHelper
12.1.6. JsonHelper
12.1.7. ScriptaculousHelper
> 12.1.8. DateFormatHelper (deprecated, I'd remove it)
> 12.1.9. Effects2Helper (deprecated, I'd remove it)
> 12.1.10. HtmlHelper (deprecated, I'd remove it)
> 12.1.11. ValidationHelper
> 12.1.12. WizardHelper

> All submissions are welcome - although I can't promise I'll use everything
> submitted in the initial round, once the new version is in the wild (and has
> been accepted by the SVN committers) people can edit and submit patches like
> any other piece of code.

How are you going to handle collaboration? Public SVN? Why dont you
use the Contrib?

[Symon Rottem]

Hey Hamilton,

Good suggestions. Are the new helpers you've listed only available in the trunk or are they also included in RC2?  I haven't used them yet myself.

Collaboration isn't something I've thought too much about yet.  Right now I'm pretty focused on just trying to get the initial revamp done for the MonoRail section so there's a structure to work from.  After I've got something that builds and contains the existing website content I'll find a way for everyone else to make edits and contributions.

Cheerio,

Symon.

[Hamilton Verissimo]

> Good suggestions. Are the new helpers you've listed only available in the
> trunk or are they also included in RC2? I haven't used them yet myself.

RC3 I think

> Collaboration isn't something I've thought too much about yet. Right now
> I'm pretty focused on just trying to get the initial revamp done for the
> MonoRail section so there's a structure to work from. After I've got
> something that builds and contains the existing website content I'll find a
> way for everyone else to make edits and contributions.

Sounds good.

[Ken Egozi]

should we aim that to RC level (-1) or to the trunk level (+1)?

--
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]

Hm.  Ok, looking at this again I think maybe I've been confused about the versioning scheme.

I was planning on starting from the older release of the documentation and working forward to the version that hasn't yet been released based on the following statement in the documentation section for each of the frameworks:

"We will keep the documentation for old version to not let down people maintained applications and unable to update for any reason."

Looking at this again I see that RC3 is referring to the overall release of the entire Castle stack and that contains MonoRail RC3, but the online MonoRail documentation refers to RC2 and trunk versions.  Does that make the trunk version referred to there RC3?.

Thinking about it again I suspect that there's going to be too much work to try to migrate *all* the old documentation so we should be targeting the trunk, but if we're expecting a long wait for the next release I don't want to leave everyone else hanging - those using the current release could certainly benefit from something that is at least repackaged (even if we don't refactor the content). 

If the expectation is that the next release is coming shortly I'll focus exclusively on the trunk, otherwise I'll do the version that's currently in the wild and to the trunk afterward.  Does anyone have a feeling about when the next release is coming?

I guess the nice thing about the docs is that their release cycle doesn't need to be directly tied to the code release cycle - at least not for updates to old revisions.

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

[Markus Zywitza]

I think that people using RCx right now don't have a problem with
documentation. Remember, the problem is not that there is no
documentation, but that it is hard for a newcomer to get into it.

I would therefore target trunk for the new documentation and then
maintain releasewise, i.e. finish the docs for 1.0 final (which will
be maintained for a long time according to Hamilton) and then work
simultaneously on 1.0 and trunk versions.

-Markus

[Ken Egozi]

+1 for that

[Symon Rottem]

OK, based on that I'll build out the initial structure based on the content from the existing "trunk" docs on the website for each framework so I have somewhere to start from, then we can go through that to make structural changes if required, refactor the content and identify any errata that needs addressing.

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

[James Curran]

A small adjustment
  12. Helpers
     12.1 Using a helper
     12.2. Built In Helpers
        12.2.1. etc

     12.3 Creating a helper

Always "using" before "creating".   Why would I want to create one until I knew what they were good for?
--
Truth,
   James

[Symon Rottem]

Thanks James - that's been fixed.  I've followed Hamilton's suggestion from earlier - there's actually going to be a lot more sub-sections in Helpers and the order has been adjusted to make more sense.

I've been working away at getting the old content into the new structure and have made some other adjustments along the way.  I think I'll have something to show tomorrow so people can comment on something more up to date.

Cheers,

Symon.

[Fiorentino]

What do you think about translating it to other languages?
I can contribute to the project working on a brazilian portuguese
translation.

Bruno Fiorentino

On 8 mar, 20:15, "Symon Rottem" <s.rot...@gmail.com> wrote:
> Thanks James - that's been fixed. I've followed Hamilton's suggestion from
> earlier - there's actually going to be a lot more sub-sections in Helpers
> and the order has been adjusted to make more sense.
>
> I've been working away at getting the old content into the new structure and
> have made some other adjustments along the way. I think I'll have something
> to show tomorrow so people can comment on something more up to date.
>
> Cheers,
>
> Symon.
>

> On Sun, Mar 9, 2008 at 12:11 AM, James Curran <james.cur...@gmail.com>

[Symon Rottem]

An excellent idea.  We should probably only do translations once we've reached a point where the content is considered ready for release though, otherwise there will be a lot of wasted effort.

Cheers,

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

On Sun, Mar 9, 2008 at 2:31 AM, Fiorentino <bruno.fi...@gmail.com> wrote:

What do you think about translating it to other languages?
I can contribute to the project working on a brazilian portuguese
translation.

On 3 mar, 21:29, "Hamilton Verissimo" <hamm...@castlestronghold.com>
wrote:
> :-)

>
> On 3/3/08, Ayende Rahien <aye...@ayende.com> wrote:
>
> > Yes, the underlying assumption that by the time you are done understanding
> > DP you don't have the strength to write docs.
>
> --
> Cheers,
> hamilton verissimo

> hamm...@castlestronghold.comhttp://www.castlestronghold.com/

[Ken Egozi]

agreed

[Markus Zywitza]

Sorry, but I'm against it. Of course, if you're not good at English
and want to contribute, I believe that every contribution in any
language is welcome. However, everyone proficient at English should
rather contribute to the English docs, so that we have at least one
set of docs complete and actual.

-Markus

[Gianluca Gravina]

If interested I can translate in italian.

 

Let me know.

 

Gianluca Gravina

[Ken Egozi]

Marcus - what if someone *can* translate, but *can't* create new docs (for lack on Castle or documentation or language knowledge)?

of course priority 2 is to create the english docs (priority 1 being the Component Burden ...), however if anyone like to contribute translations I think we should welcome that.

[Markus Zywitza]

That's what I have written, but I think that most people writing here
have enough knowledge of English to create docs or at least check and
counterread the docs written by others. Remember, we are not going for
the Pulitzer price, but want to create technical docs instead.

-Markus

[Jan Limpens]

I heard that phyton allows to attach unit tests to pieces of documentation. It would then allow to run those tests on compilation of the output formats. I think this is a great way to ensure that documentation and actual programming are kept in synch.

Of course python has the advantage of not needing compilation, but maybe brail could be used for that.

jan

--
Jan
___________________
j...@limpens.com
www.limpens.com
+55 (11) 3082-1087
+55 (11) 3097-8339

[Symon Rottem]

I believe both can be addressed at the same time easily enough.  Ken has a point - some people don't understand how Castle works or they can understand English but can't author well.  These people can often provide a valuable contribution by translating existing texts.

Ideally we should be getting the documentation into a releasable state and *at that point* we should be getting translations done to improve the reach of the frameworks.  Agreed, the translations are not the top priority, but if someone wants to volunteer I'm certainly not going to turn them away.

Cheers,

Symon.

[Ken Egozi]

I think DP2 code is certainly Pulitzer material.

[Symon Rottem]

Is anyone prepared to try for the prize and write some docs for it though?  I'm happy enough even if it's done in broken English as long as I have something to work from...I have *no* idea how it works yet and I don't think I have the available cycles to figure it out at the moment.

Do this and you'll win the prize as far as I'm concerned...

Symon.

On Sun, Mar 9, 2008 at 1:03 PM, Ken Egozi <ego...@gmail.com> wrote:

I think DP2 code is certainly Pulitzer material.

[grava]

Not only pulitzer, I think asimov, if alive, shuold be impressed from
how much fiction there's in it !

:)

I agree on pririotize English docs. Hopefully, when English docs are
ready I could contribute, I'm not so good with english to author a
document,

Bye,

Gianluca Gravina

On Mar 9, 1:03 pm, "Ken Egozi" <egoz...@gmail.com> wrote:
> I think DP2 code is certainly Pulitzer material.
>
>
>
> On Sun, Mar 9, 2008 at 2:00 PM, Symon Rottem <s.rot...@gmail.com> wrote:
> > I believe both can be addressed at the same time easily enough. Ken has a
> > point - some people don't understand how Castle works or they can understand
> > English but can't author well. These people can often provide a valuable
> > contribution by translating existing texts.
>
> > Ideally we should be getting the documentation into a releasable state and
> > *at that point* we should be getting translations done to improve the reach
> > of the frameworks. Agreed, the translations are not the top priority, but
> > if someone wants to volunteer I'm certainly not going to turn them away.
>
> > Cheers,
>
> > Symon.
>

> > On Sun, Mar 9, 2008 at 12:53 PM, Markus Zywitza <markus.zywi...@gmail.com>

> > wrote:
>
> > > That's what I have written, but I think that most people writing here
> > > have enough knowledge of English to create docs or at least check and
> > > counterread the docs written by others. Remember, we are not going for
> > > the Pulitzer price, but want to create technical docs instead.
>
> > > -Markus
>

> > > bruno.fiorent...@gmail.com>

[Hamilton Verissimo]

Translations will run out of date in no time. Also, we have put
together a forum in pt-br and it's been a fiasco. I'm +1 to leave it
all in english.

[Symon Rottem]

Well I suppose at worst people can download the source for the documentation, do a translation and bung it up on Contib or the wiki if they want to share it.

Symon.

[Bruno Fiorentino]

I´ve seen an opportunity to collaborate and stay really up to date on these new documents.
I´d agree that those translations should start from well defined english releases.

I can read and understand english well --specifically technical content -- I´m always reading
[english] books, articles and blogs, however I have difficulty to listen and express my "portuguese
based thoughts" in english (I´m getting classes to address this issues).

Leave all the communication flow in one language may have advantages, but
I beleave pt-br translations could help a few brazilian C# developers start to improve
their way of thinking by "undertanding that there is life outside MSDN".

I don´t know what is the best strategy, If you decide to translate it, let me know.

I´m curious about that brazilian forum. What happened?

Bruno Fiorentino

[Henry Conceição]

Translations will be a waste of time and effort. We barely can
maintain a decent docs in English, imagine it with 3 ou 4 fours
differents languages. Like Hammett said, it'll be outdated in no time.

--
Cheers,
Henry Conceição

[Bruno Fiorentino]

I beleave translate is an easy. The hard work, in my opinion, is left to people that are gonna find the best approach to expose frameworks concepts and behaviors. I like technical translations that preserve english keywords and concepts.

Bruno Fiorentino

[Henry Conceição]

Translate is easy, for sure. The tricky is to keep it updated. IMHO,
outdated docs are worst than no doc.

On Sun, Mar 9, 2008 at 10:23 PM, Bruno Fiorentino

--
Cheers,
Henry Conceição

[Bruno Fiorentino]

What´s the estimated size (in pages ? - think of an o´really book page) of this document?

Bruno Fiorentino

[Bruno Fiorentino]

Well, I motivated to do that, but I guess it´s something hard to estimate and I´d agree
outdated docs are undesireble. Let´s wait for the new docs first release.
We´re gonna know it´s size and upgrading needs then, with those informations,
it´ll be easy continue to talk about it.

Thanks,
Bruno Fiorentino

[Symon Rottem]

Ok,  I've managed to get the MonoRail documentation converted to DocBook, reorganize the content and render to chunked HTML.  At this stage I haven't refactored the content at all and the styling is only rudimentary at this stage but something better (including syntax highlighting for the code samples) should be forthcoming fairly soon.  The structure has changed somewhat since my original post and includes a lot more information.

 

You can find it here for review purposes:

 

http://www.symbiotic-development.com/symbiotic/monorail_docs/index.html

 

Please take a look - I'd appreciate some feedback. 

 

I've also had some success in generating a single page HTML version and a CHM file (although the styling there is not really appropriate for reivew yet).  PDF should be coming soon. 

 

Cheers,

 

Symon.

[Gianluca Gravina]

I just have a quick look … great job Symon.

 

Gianluca Gravina

 

 

From: castle-pro...@googlegroups.com [mailto:castle-pro...@googlegroups.com] On Behalf Of Symon Rottem
Sent: lunedì 10 marzo 2008 12.12
To: castle-pro...@googlegroups.com
Subject: Re: Documentation

 

Ok,  I've managed to get the MonoRail documentation converted to DocBook, reorganize the content and render to chunked HTML.  At this stage I haven't refactored the content at all and the styling is only rudimentary at this stage but something better (including syntax highlighting for the code samples) should be forthcoming fairly soon.  The structure has changed somewhat since my original post and includes a lot more information.

[Ken Egozi]

Great job Symon. looks like youre progressing well.

where did ya take the data from though? a quick peek at ViewEngineComparisson showed different things from the current trunk docs

http://castleproject.org/monorail/documentation/trunk/viewengines/comparisson.html
http://www.symbiotic-development.com/symbiotic/monorail_docs/ch08.html#id509430

did you do manual changes?

On Mon, Mar 10, 2008 at 1:22 PM, Gianluca Gravina <gianluca...@gmail.com> wrote:

I just have a quick look ... great job Symon.

[Patrick Steele]

Wow! Looks awesome. Great work!

[Bruno Fiorentino]

Great work!

[Markus Zywitza]

Good work.

What I have seen during a first look:
-Remove numbering from headings level 4+ would be advisable. Headings
that read like IPv6-addresses don't serve readability ;-)
-Some pictures didn't make it to the new docs.
-HTML/XML entities need to be reviewed. I remember I needed an ugly
hack for them in the Anakia docs, so this was rather expected.

Now, the question is, what should be the master docs? Anakia source or docbook?

-Markus

[Symon Rottem]

Thanks Markus,

 

I debated the level 4 headings and my feeling was that there was still value as they should appear in the index - I took this approach based on the Spring.NET documentation, which I feel is an excellent resource.  It's easy to change in the future anyway - simply a parameter to the docbook XSL.

I'll look into the pictures - I probably missed a path statement or two during the cut and paste phase.  If you can tell me the section numbers I'll fix them tout de suite.

 

I'm not sure what you're referring to with the HTML/XML entites...

 

Before I release the changed source I am going to clean up the process automation (build scripts, etc).  After that's ready I'd be inclined to look at using these as the master docs.

 

In terms of presentation on the website though, should these be waiting for the next release or could these current docs be release as a replacement for the current RC3 release that's already out?  I think that since the content is the same as the "trunk" version of the docs on the website they match the current RC3 release, right?

 

Symon.

[Ben Lovell]

Excellent job.  

Sent from my iPhone

[Markus Zywitza]

I reviewed the section about DiggStylePagination-Component. There is
one pic missing and I used &laquo; and &raquo; in the text, however,
in the Anakia source I needed to write &amp;laquo; to have &laquo; in
the generated HTML to display the right character (<<) on the screen.
This is what I referred to with dirty hack.

-Markus

[Symon Rottem]

Oh, OK - I see the problem.  I'll sort that out.

 

There are a couple of other format related issues like the layout of some of the code samples have been munged but I should be able to fix those easily enough too.

 

Symon.

[Ken Egozi]

Naaa, that ain't dirty.

That's dirty:
OnDataItemShittyEventWeirdThing e)
{
   ((TextBox)e.Cells[3].FindControl("wtf")).Text = someCrap;

[Alessandro Riolo]

On 1 Mar, 17:37, "Hamilton Verissimo" <hamm...@castlestronghold.com>
wrote:
> MonoRail is going to die if, and only if, MS MVC is so fantastic that
> even I wont find a good reason to still using MonoRail. Is that a safe
> bet? I dont know. It's hard to tell. I'm inclined to think that wont
> be the case. MR will still be a good option for more hardcore
> developer.

I would like to add that, even if MS MVC would be so fantastic, whch
from what I saw so far I do sincerely doubt, if they patch it every
couple of years, and if when they patch it they don't really fix what
should be fixed because would break God only knows how many work
arounds, well, MonoRail will not die the same.

--
ale
http://ale.riolo.co.uk

[Symon Rottem]

Who can help me out with some credentials to put the new documentation into source control?  I'd like to put it into the Contrib repository.

I'm also interested in what action should be taken going forward.  Ideally I'd prefer to see people reviewing the work and then to discuss where we can host the HTML version and whether or not we can point to it from the website.  Since it's simply a copy of the current source of the trunk version of the MonoRail docs at this point is there any reason not to?

Anyone got any guidance on what to do next?

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

[Hamilton Verissimo]

On 3/13/08, Symon Rottem <s.ro...@gmail.com> wrote:
> Who can help me out with some credentials to put the new documentation into
> source control? I'd like to put it into the Contrib repository.

Contact me privately.

> I'm also interested in what action should be taken going forward. Ideally
> I'd prefer to see people reviewing the work and then to discuss where we can
> host the HTML version and whether or not we can point to it from the
> website. Since it's simply a copy of the current source of the trunk
> version of the MonoRail docs at this point is there any reason not to?

What about docs.castleproject.org ?

[Sean Chambers]

When you guys get something up, if you let me know where it is located
I will read through it and see if I can find any errors or anything.
I'm excited to see how it is all organized. This is a really great
step in the right direction. cheers Symon!

To add to what Alessandro said, the driving force for me using
MonoRail is the fact that bugs are fixed so quickly and not to mention
the fact that it is open source. I hope it isn't going anywhere soon!

Sean

On Mar 13, 5:52 pm, "Hamilton Verissimo"
<hamm...@castlestronghold.com> wrote:

> On 3/13/08, Symon Rottem <s.rot...@gmail.com> wrote:
>
> > Who can help me out with some credentials to put the new documentation into
> > source control?  I'd like to put it into the Contrib repository.
>
> Contact me privately.
>
> > I'm also interested in what action should be taken going forward.  Ideally
> > I'd prefer to see people reviewing the work and then to discuss where we can
> > host the HTML version and whether or not we can point to it from the
> > website.  Since it's simply a copy of the current source of the trunk
> > version of the MonoRail docs at this point is there any reason not to?
>
> What about docs.castleproject.org ?
>
> --
> Cheers,
> hamilton verissimo

> hamm...@castlestronghold.comhttp://www.castlestronghold.com/