Documentation Contributions

time to read 1 min | 54 words

This is a question for the audience, assume that you have 500$, what would be the best way to spend them in a way that would improve the documentation for Castle, NHibernate or Rhino Tools?

(Just to point out, the 500$ is not related in any way to Jeff's donations, except the overall idea)

Tweet Share Share 11 comments

Tags:

Open Source

Comments

27 Jun 2007
20:40 PM

Mike

Sample projects are by far most helpful for me .

Castle has some but they are often out of date (for example, trying to learn Brail is better with your sample application and not the castle samples).

NHibernate has a few good samples out there but I don't really agree with the way they consume NHibernate services since they focus on how NHibernate works rather than how NHibernate integrates into an app.

I am not sure how money would produce this unless you pay someone to commit to a day or two to create sample projects with a variety of structures and setups using these tools. I want to do just that but time keeps me from following through.

27 Jun 2007
20:51 PM

Ken Egozi

What about getting all those 500$ changed to the lowest-value-coin-you-can-find (with up to 3 queries), and then write a huge I-(^^)-NHibernate through the Grand-Canyon? No that's evangelizing !!

27 Jun 2007
21:30 PM

Brennan Stehling

Perhaps the best thing you could do is purchase a very good wiki like Confluence. Since you are already running a popular open source project you can probably get a free license anyway.

http://www.atlassian.com/software/confluence/

The ease of use of their wiki actually makes writing up new documentation a breeze. It also indexes all kinds of document formats like Word and PDF and makes it all searchable. If you can get a free license you could spend the $500 on graphic designer to ensure everything looks great and is very readable. A good layout designer is worth the money, although $500 is not exactly a ton of money.

27 Jun 2007
21:45 PM

Ayende Rahien

@Brennan,

All projects already have a wiki or equivalent

Castle has http://using.castleproject.org - which is confluence

NHibernate has the JBoss' system

Rhino Tools has http://www.ayende.com/Wiki - ScrewTurn wiki

I am more interested in getting content created than the mechanics of that.

28 Jun 2007
01:41 AM

hammett

I had some hard time getting up to speed with Rhino.Mocks, so I think a getting started would be useful. But who am I to complain about documentation? ;-)

28 Jun 2007
02:39 AM

Mike Minutillo

What I would love to see from Castle (and may other larger frameworks) is a separate project which goes through the construction of a complete application from beginning to end.

The project would have screencasts of important topics and a blog where contributors can talk about their experience.

This is likely going to be very time-consuming and so I don't think it is up to the core contributors of the project to do the actual work here.

Also I don't think that $500 would cover it. What it would do is increase the public exposure of the framework. It might even cause a media ruckus :)

28 Jun 2007
05:20 AM

Ayende Rahien

Hammett, did you get a chance to see the Hibernating Rhinos #1 ?

28 Jun 2007
05:22 AM

Ayende Rahien

Michael,

That is what I am doing now with the Hibernating Forums stuff. It has a different focus, but it should do to teach how you can use that.

28 Jun 2007
06:02 AM

Torkel

I agree with Mike, seeing the process of building a real world application is to me most help full in understanding how a framework should/can be used.

28 Jun 2007
12:13 PM

Tommaso Caldarola

Donate it to poors...

28 Jun 2007
20:52 PM

hammett

Michael/Torkel, that's stuff for a book, not screencasts. It's just too many things involved.

Ayende, not sure I did. I really googled a lot for it. I believe my problem was handling things with no return value. Took a while to get to LastCall and understand how I was supposed to use it. But I might be getting old....

Comment preview

Comments have been closed on this topic.

Markdown turns plain text formatting into fancy HTML formatting.

Phrase Emphasis

*italic*   **bold**
_italic_   __bold__

Links

Inline:

An [example](http://url.com/ "Title")

Reference-style labels (titles are optional):

An [example][id]. Then, anywhere
else in the doc, define the link:
  [id]: http://example.com/  "Title"

Images

Inline (titles are optional):

![alt text](/path/img.jpg "Title")

Reference-style:

![alt text][id]
[id]: /url/to/img.jpg "Title"

Headers

Setext-style:

Header 1
========
Header 2
--------

atx-style (closing #'s are optional):

# Header 1 #
## Header 2 ##
###### Header 6

Lists

Ordered, without paragraphs:

1.  Foo
2.  Bar

Unordered, with paragraphs:

*   A list item.
    With multiple paragraphs.
*   Bar

You can nest them:

*   Abacus
    * answer
*   Bubbles
    1.  bunk
    2.  bupkis
        * BELITTLER
    3. burper
*   Cunning

Blockquotes

> Email-style angle brackets
> are used for blockquotes.
> > And, they can be nested.
> #### Headers in blockquotes
> 
> * You can quote a list.
> * Etc.

Horizontal Rules

Three or more dashes or asterisks:

---
* * *
- - - -

Manual Line Breaks

End a line with two or more spaces:

Roses are red,   
Violets are blue.

Fenced Code Blocks

Code blocks delimited by 3 or more backticks or tildas:

```
This is a preformatted
code block
```

Header IDs

Set the id of headings with {#<id>} at end of heading line:

## My Heading {#myheading}

Tables

Fruit    |Color
---------|----------
Apples   |Red
Pears	 |Green
Bananas  |Yellow

Definition Lists

Term 1
: Definition 1
Term 2
: Definition 2

Footnotes

Body text with a footnote [^1]
[^1]: Footnote text here

Abbreviations

MDD <- will have title
*[MDD]: MarkdownDeep

Oren Eini

Oren Eini

CEO of RavenDB