Castle documentation

[Krzysztof Koźmic (2)]

Let's move the docs discussion to a new thread.

Now, about wiki,

I did a quick research, about how other frameworks handle that:

JQuery - wiki, password protected (at least, I don't know if they have
any other mechanisms, like moderation or captcha)

Dojo toolkit - wiki, (? - there's edit link)

Ruby on Rails - docs generated from text files in their Git repository
(http://guides.rubyonrails.org/contribute.html)

CakePHP - wiki (PP)

Zend - ? (Docs seem to be static, and I didn't find any info about
ways of contributing to the docs)

Django - "Django’s documentation uses the Sphinx documentation system,
which in turn is based on docutils. The basic idea is that lightly-
formatted plain-text documentation is transformed into HTML, PDF, and
any other output format.", they use bug tracker to accept docs
patches, similar to Castle AFAICT

[alwin]

Some form of wiki as official docs would be great IMO. I don't know
how exactly jQuery does it, but it works really good. NHForge wiki is
also nice for the reader, although a bit disorganized.

I've written some stuff on the castle using site, but when you put
something there it doesn't get noticed by many. Also it's cumbersome
to write something there.

If it would be easy and encouraged for bloggers to copy the content of
their blogposts to the wiki, you get a lot of content fast (I hope).

[Roelof Blom]

jQuery docs is mediawiki, and despite that it's looking great.

2009/9/25 alwin <alw...@gmail.com>

[Krzysztof Koźmic (2)]

You brought up an interesting point - the 'Using' site.

It is not really working well. Content there is not discoverable, and
the Using site itself is confUsing, as to how it relates to the docs.

I think we should have one Docs site, with Usage Guide and API
sections, much like JQuery does.

[Jonathon Rossi]

We also have http://api.castleproject.org/ which I doubt many people use.

I think building one set of docs from everything is the way to go.

2009/9/25 Krzysztof Koźmic (2) <krzy...@kozmic.pl>

--
Jono

[Roelof Blom]

One set of docs *per* project I guess

2009/9/25 Jonathon Rossi <jo...@jonorossi.com>

[Krzysztof Koźmic (2)]

I'm not sure about that.
Both have pros and cons.
Especially usage guides could benefit if you discuss how all the
projects play together...

Plus if you wanted to keep them separate, what would you do about
small projects, like DictionaryAdapter...
Of course given each project has different release cycles they would
need to be updated at different times...
I think the best option lies between. Keep the docs together, with
sections dedicated to certain projects/versions

ideas?

On 25 Wrz, 13:02, Roelof Blom <roelof.b...@gmail.com> wrote:
> One set of docs *per* project I guess
>

> 2009/9/25 Jonathon Rossi <j...@jonorossi.com>
>
> > We also havehttp://api.castleproject.org/which I doubt many people use.

>
> > I think building one set of docs from everything is the way to go.
>

> > 2009/9/25 Krzysztof Koźmic (2) <krzysz...@kozmic.pl>

[Jonathon Rossi]

It does depend on where we decide to store our docs, we do want to make it fairly easy to link between documentation for projects but they do need some separation.

I always thought that a markdown based help system would be nice, but I don't think anyone has made one. The advantage I see of markdown is that you can nearly just use it as an output medium that you can read from.

One problem with a wiki is that it is much more difficult to contribute offline (I'm not just referring to network connectivity: you wouldn't always want draft documentation online straight away). Another advantage of storing documentation with the source is that you can get spam in subversion, so if we do go with a wiki we must have some review process for non-committers/approved writers, otherwise we'll just end up with heaps of spam in the docs.

2009/9/25 Krzysztof Koźmic (2) <krzy...@kozmic.pl>

--
Jono

[Henry Conceição]

Sorry guys, but I don't want to spend time installing with a wiki and
see outdated as our current docs.

We tried it in the past, with a customized version of mediawiki. The
documentation usability was horrible and the contributions were as
much that we see today. I don't buy the "ooh, if it was a wiki instead
of static pages I would contribute more and more".


Cheers,
Henry Conceição



2009/9/25 Jonathon Rossi <jo...@jonorossi.com>:

[John Simons]

Guys,
I understand you have tried a wiki before and it didn't work, but the
current process is not working either.

Currently is quite complicated to update the doco:
- Get latest from svn;
- find the page that you want to update;
- Learn a new syntax (it is not just plain html)
- Do the update (and this could be just fixing a spelling mistake)
- Create patch
- Submit patch to Donjon (find where to submit patch in Donjon)
- Wait for someone to review and apply patch
- Wait for upload process to update web site pages

As you can see too many steps!

We need to do something to improve the submitting and reviewing of
doco for us and our users.

I agree that the API doco is a waste of time, and combing all doco in
one place is the way to go.

@Henry, you now have new people contributing, I think it is worth
trying the wiki way again and has Krzysztof points out, it can be very
successful.

John

On Sep 26, 2:46 am, Henry Conceição <henry.concei...@gmail.com> wrote:
> Sorry guys, but I don't want to spend time installing with a wiki and
> see outdated as our current docs.
>
> We tried it in the past, with a customized version of mediawiki. The
> documentation usability was horrible and the contributions were as
> much that we see today. I don't buy the "ooh, if it was a wiki instead
> of static pages I would contribute more and more".
>
> Cheers,
> Henry Conceição
>

> 2009/9/25 Jonathon Rossi <j...@jonorossi.com>:

>
> > It does depend on where we decide to store our docs, we do want to make it
> > fairly easy to link between documentation for projects but they do need some
> > separation.
>
> > I always thought that a markdown based help system would be nice, but I
> > don't think anyone has made one. The advantage I see of markdown is that you
> > can nearly just use it as an output medium that you can read from.
>
> > One problem with a wiki is that it is much more difficult to contribute
> > offline (I'm not just referring to network connectivity: you wouldn't always
> > want draft documentation online straight away). Another advantage of storing
> > documentation with the source is that you can get spam in subversion, so if
> > we do go with a wiki we must have some review process for
> > non-committers/approved writers, otherwise we'll just end up with heaps of
> > spam in the docs.
>

> > 2009/9/25 Krzysztof Koźmic (2) <krzysz...@kozmic.pl>

>
> >> I'm not sure about that.
> >> Both have pros and cons.
> >> Especially usage guides could benefit if you discuss how all the
> >> projects play together...
>
> >> Plus if you wanted to keep them separate, what would you do about
> >> small projects, like DictionaryAdapter...
> >> Of course given each project has different release cycles they would
> >> need to be updated at different times...
> >> I think the best option lies between. Keep the docs together, with
> >> sections dedicated to certain projects/versions
>
> >> ideas?
>
> >> On 25 Wrz, 13:02, Roelof Blom <roelof.b...@gmail.com> wrote:
> >> > One set of docs *per* project I guess
>
> >> > 2009/9/25 Jonathon Rossi <j...@jonorossi.com>
>

> >> > > We also havehttp://api.castleproject.org/whichI doubt many people

[Henry Conceição]

I'm still skeptic.

This discussion pops from time to time (do a quick search if you don't
believe me), a bunch of people come with great ideas about how we
should do it, a lot of people cast a vote and say let's do it, and one
month later everything has stopped. The documentation as docbook
initiative comes to my mind.

And btw, the efforts to setup a wiki, customize it, copy all the web
site content and etc are more than enough to update the current docs,
imho.

But if you believe this time will be different, you can setup a wiki
somewhere, do all this work that I mentioned and change the links on
the homepage. If two months later it still continues to receive
contributions, I'll be _very_ happy to recognize that I'm wrong and
setup it's as the new official castle project documentation website.

Take a look on the using.castleproject for example. It started in
discussion like this, with the same arguments. And today it has some
valuable content but we don't see a lot of contributions, new articles
and etc.

Cheers,
Henry Conceição

[John Simons]

I see your point Henry.

Setting up a new wiki + migrating the doco is not going to changes our
commitment to keep the doco up-to-date,
and I think that is what we are failing on.

What I don't like is 3 different sites (API doco, Using and Web Site)
with doco on. We should bring all these together.

I think it should be part/mandatory of a project release to update the
doco (in one place, not 3!).

Also, I know it is not considered a doco site but I think the users
mailing list also has a considerable amount of doco/tips/usage. So
this actually brings the number up to 4 sites with doco.

Cheers
John

On Sep 26, 9:54 am, Henry Conceição <henry.concei...@gmail.com> wrote:
> I'm still skeptic.
>
> This discussion pops from time to time (do a quick search if you don't
> believe me), a bunch of people come with great ideas about how we
> should do it, a lot of people cast a vote and say let's do it, and one
> month later everything has stopped. The documentation as docbook
> initiative comes to my mind.
>
> And btw, the efforts to setup a wiki, customize it, copy all the web
> site content and etc are more than enough to update the current docs,
> imho.
>
> But if you believe this time will be different, you can setup a wiki
> somewhere, do all this work that I mentioned and change the links on
> the homepage. If two months later it still continues to receive
> contributions, I'll be _very_ happy to recognize that I'm wrong and
> setup it's as the new official castle project documentation website.
>
> Take a look on the using.castleproject for example. It started in
> discussion like this, with the same arguments. And today it has some
> valuable content but we don't see a lot of contributions, new articles
> and etc.
>
> Cheers,
> Henry Conceição
>

> >> >> > > We also havehttp://api.castleproject.org/whichIdoubt many people

[Jonathon Rossi]

I am with you Henry, we do keep having this discussion and things go nowhere because everyone is very limited on time; and coding is more fun.

Is anyone aware of how projects like Spring and Maven keep their docbook based books/docs up to date? Do they have someone who contributes a lot of their time to updating the documentation? Maven seems to run their opensource book as a separate project in their community with its own issue tracker (https://issues.sonatype.org/browse/MVNDEF) and everything.

http://www.sonatype.com/documentation/books/maven-defguide
http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/

Symon Rottem's attempt at getting Castle using docbook makes things look nicer, but we have to actually update the documentation.
http://www.symbiotic-development.com/monorail/html/chunked/index.html

--
Jono

[Krzysztof Koźmic]

Getting back to this (and confluence spam issues).
I did some research in the meantime, trying out screw turn wiki and to a
lesser extent media wiki.

They both have quite good options in terms of securing content and
blocking vandalism...
Also they both can be integrated with Re-Captcha, and since STW is
written in .NET, we could easily integrate Akismet with it as well.

Now, these options would require starting from scratch, so we might try
updating the Using site to new version of Confluence (the current one is
3yo)
and if the new version is better, stick to confluence, and start
migrating all docs there, ultimately phasing out current docs.

But first of all - let's act. I would suggest starting with update to
Confluence, since that would be probably least hassle in the long run.

Henry, could you do it?

Krzysztof