New documentation required

[Jakub Fojtl]

I am very unhappy with the state of the actual documentation of Castle Windsor (I'm not using any other project from Castle so much). It is very hard to start with Castle Windsor, there is no Getting started, it is badly organized (probably hate the navigation of ScrewTurn wiki), important parts of CW like WCF Facility, Handlers etc is documented so little, that from the documentation, I would not be able to even understand what it is good for.

Is it just me who is unsatisfied with the actual state? Or is there already a new documentation growing somewhere else?

Thanks,

Jakub.

[Krzysztof Kozmic]

Hi Jakub.

So it feels to me like you're raising two different problems.

1. the doco content is lacking

2. the STW sucks and is dead as a doornail (and therefore not going to get any better)

I do agree with both. There are gaps in the doco quality. It is an open wiki however so I would encourage you (or anyone) to help improving it, adding bits of content here and there, cleaning it up to make things simpler to understand etc.

About STW… I'd love to move to a better system, but I'd need someone to commit to migrating the content, as this is a major task, and one I won't have the time to do myself. Also the question arises - what should we use? github wiki? something else?

Basically Windsor (Castle in general) is going to be only as good as the community contributing to it makes it, so it's an opportunity for everyone here to dedicate some of your knowledge, skill and time to help it get better.

-- 

Krzysztof Kozmic

--
You received this message because you are subscribed to the Google Groups "Castle Project Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-u...@googlegroups.com.
To post to this group, send email to castle-pro...@googlegroups.com.
Visit this group at http://groups.google.com/group/castle-project-users.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Jakub Fojtl]

Hi,

Thanks for your answer.

I have no problem with such commitment but I would like to come up with kind of a plan or direction we would like to go and then start on it. I do not see much sense in editing/expanding nowadays articles without clear target.

[Krzysztof Kozmic]

ok,

what sort of target did you have in mind. A quality one? A content one? A structural one? Or in general a roadmap of what are we going to do with the STW docs?

Also, what are the others thinking?

-- 

Krzysztof Kozmic

--

[Jakub Fojtl]

I had a sort of a roadmap in mind. Getting started series "for dumies", easy to read and follow. And then sections for each feature more "in depth".

But before that, I think it is crucial to pick better software. While I like the GitHub wiki, I don't think that its "flat structure" is enough for my intentions. I would go with something like octopress - markdown syntax, versioned in git, highly customizable and hosted on GitHub.

What do you think?

You received this message because you are subscribed to a topic in the Google Groups "Castle Project Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/castle-project-users/4JOsZ4mGZaE/unsubscribe.
To unsubscribe from this group and all its topics, send an email to castle-project-u...@googlegroups.com.

[Krzysztof Koźmic]

What specifically don't you like about github wiki?

Krzysztof

sent from my phone

[Jakub Fojtl]

Hi,

 

As I said, I do not like the flat structure.

 

There is just one navigation component – the list of all pages which is great for little to medium projects. In case of Castle Windsor, there is (and should be) so many pages that the control would end up the same as with current SWT. Extremely hard to navigate.

 

I don’t know, I was thinking about something smarter.

[Krzysztof Kozmic]

We could build an index page grouping things in a more organised way if needed on github.

I like the idea of using github pages. They are simple to contribute to, have decent search and work OOTB requiring no setup and unlike STW are likely to keep getting better.

Anyway, the main issue, whatever we do, would be getting people to actually contribute content/port the old content over.

-- 

Krzysztof Kozmic

[Jakub Fojtl]

Now I'm confused, GH pages or wiki? :)

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-users+unsub...@googlegroups.com.

To post to this group, send email to castle-pro...@googlegroups.com.
Visit this group at http://groups.google.com/group/castle-project-users.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
You received this message because you are subscribed to a topic in the Google Groups "Castle Project Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/castle-project-users/4JOsZ4mGZaE/unsubscribe.

To unsubscribe from this group and all its topics, send an email to castle-project-users+unsub...@googlegroups.com.

To post to this group, send email to castle-pro...@googlegroups.com.
Visit this group at http://groups.google.com/group/castle-project-users.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "Castle Project Users" group.

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-users+unsub...@googlegroups.com.

To post to this group, send email to castle-pro...@googlegroups.com.
Visit this group at http://groups.google.com/group/castle-project-users.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
You received this message because you are subscribed to a topic in the Google Groups "Castle Project Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/castle-project-users/4JOsZ4mGZaE/unsubscribe.

To unsubscribe from this group and all its topics, send an email to castle-project-users+unsub...@googlegroups.com.

To post to this group, send email to castle-pro...@googlegroups.com.
Visit this group at http://groups.google.com/group/castle-project-users.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
You received this message because you are subscribed to the Google Groups "Castle Project Users" group.

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-users+unsub...@googlegroups.com.

[Krzysztof Kozmic]

wiki. I meant wiki :)

-- 

Krzysztof Kozmic

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-u...@googlegroups.com.

[Aleš Roubíček]

I can participate on actual content moving.

On Thursday, August 8, 2013 11:10:37 AM UTC+2, Jakub Fojtl wrote:

[Jakub Fojtl]

Aleš,

you also vote for GH wiki?

[Aleš Roubíček]

I can't see any valid reason to have it elsewhere. :)

[Jakub Fojtl]

As I said, I think navigation is going to be a problem but it's worth a try. 

[Jakub Fojtl]

Hi Krzystof,

Is there a how to get all articles from current wiki? I registered as jfojtl but still cannot find something like "backup", "batch download" or so.

Thanks,

On Thursday, August 8, 2013 11:10:37 AM UTC+2, Jakub Fojtl wrote:

[Krzysztof Kozmic]

I'm not sure there is anything like that built in for Screw Turn Wiki...

-- 

Krzysztof Kozmic

--

[Jonathon Rossi]

Since STW is set up using SQL Server rather than the default file based store, we could get Henry or Hammett to provide a backup of the database which would be much more easily converted into separate pages than manually doing it.

--
Jono

[Aleš Roubíček]

Hi,

I actually started moving STW content into GHW in my fork (https://github.com/rarous/Windsor). I don't think there is value in backup files, because the STW syntax is not supported by GHW. IMO it is better to move the actual content by hand and improve it. 

You can see new readme.md file that contains some content from actual wiki (it is still stub) and a few pages.

There is a question, since GHW does not support upload of attachments, where to upload them? Possible solutions:

1. upload them as gist and then link raw gist.

2. push the files into wiki repository (there is no convenient way how to do it from web)

3. host the files somewhere else (ideas?)

What do you think?

On Thursday, August 8, 2013 11:10:37 AM UTC+2, Jakub Fojtl wrote:

[Krzysztof Koźmic]

What sort of attachments do we need?

--

[Jakub Fojtl]

Pictures.

I tried to use pandoc (http://johnmacfarlane.net/pandoc/), which works somehow but messes source code. We could propably fix that by creating our own writer. It's written in Haskel, so it should be fun.

On the other side, I'm not sure that 1:1 migration is what we want.

On Tuesday, August 20, 2013 7:45:51 AM UTC+2, Krzysztof Koźmic wrote:

What sort of attachments do we need?

On 20/08/2013 3:00 PM, "Aleš Roubíček" <rar...@gmail.com> wrote:

Hi,

I actually started moving STW content into GHW in my fork (https://github.com/rarous/Windsor). I don't think there is value in backup files, because the STW syntax is not supported by GHW. IMO it is better to move the actual content by hand and improve it. 

You can see new readme.md file that contains some content from actual wiki (it is still stub) and a few pages.

There is a question, since GHW does not support upload of attachments, where to upload them? Possible solutions:

1. upload them as gist and then link raw gist.

2. push the files into wiki repository (there is no convenient way how to do it from web)

3. host the files somewhere else (ideas?)

What do you think?

On Thursday, August 8, 2013 11:10:37 AM UTC+2, Jakub Fojtl wrote:

I am very unhappy with the state of the actual documentation of Castle Windsor (I'm not using any other project from Castle so much). It is very hard to start with Castle Windsor, there is no Getting started, it is badly organized (probably hate the navigation of ScrewTurn wiki), important parts of CW like WCF Facility, Handlers etc is documented so little, that from the documentation, I would not be able to even understand what it is good for.

Is it just me who is unsatisfied with the actual state? Or is there already a new documentation growing somewhere else?

Thanks,

Jakub.

--
You received this message because you are subscribed to the Google Groups "Castle Project Users" group.

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-users+unsub...@googlegroups.com.

[Krzysztof Kozmic]

images can be committed to a branch in the repository and linked from there https://help.github.com/articles/how-do-i-add-images-to-my-wiki

-- 

Krzysztof Kozmic

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-u...@googlegroups.com.

[Jakub Fojtl]

Ales said that. Problem is that it cannot be done directly from web :(

You received this message because you are subscribed to a topic in the Google Groups "Castle Project Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/castle-project-users/4JOsZ4mGZaE/unsubscribe.
To unsubscribe from this group and all its topics, send an email to castle-project-u...@googlegroups.com.

[Jakub Fojtl]

How about making a "public" google hangout?

I think agenda starts to be pretty clear, so it shouldn't be wasting our times:

1. to migrate or not to migrate current content

2. how we imagine the first public checkpoint (what needs to be done to say, now we are switching totaly from SWT to GHW)

3. how to organize the wiki (the structure - per facility? per concepts? if it was book, what are the main chapters?)

4. come up with getting started section (or improving current ToBeSeen example)

How do you like the idea? Could you propose time? I think 30-60 mins should be enough for first meeting and it will be much faster than this discussion.

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-users+unsubscrib...@googlegroups.com.

To post to this group, send email to castle-pro...@googlegroups.com.
Visit this group at http://groups.google.com/group/castle-project-users.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "Castle Project Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-users+unsub...@googlegroups.com.

To post to this group, send email to castle-project-users@googlegroups.com.

Visit this group at http://groups.google.com/group/castle-project-users.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to a topic in the Google Groups "Castle Project Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/castle-project-users/4JOsZ4mGZaE/unsubscribe.

To unsubscribe from this group and all its topics, send an email to castle-project-users+unsub...@googlegroups.com.
To post to this group, send email to castle-project-users@googlegroups.com.

[Aleš Roubíček]

don't forget that stw doc has pretty good ranking in google, we have to handle old uris somehow.

[Krzysztof Koźmic]

We can keep the old doco and add a message about it being outdated, and redirect to the new one, or redirect directly.

How's the rest going? The migration and update?

Krzysztof

[Mauricio Scheffer]

Hi all,

I recently moved some documentation to Github and faced the same decision: wiki, gh-pages, or loose markup files? I'd like to offer my thoughts about it.

The problem with Github wikis is that they're either fully public (meaning there's a potential for spam or incorrect content) or closed to collaborators, without the possibility for pull requests.

There have been cases of wiki spam on Github: https://groups.google.com/forum/#!topic/bigjob-users/AGZr_UN0RZc http://rants.arantius.com/github-sucks

With markup files or gh-pages, anyone with a github account can click "edit", make a change, and Github will automatically fork the repo and create the corresponding pull request. The contributor doesn't even have to know much about git.

This is also similar to the old website https://github.com/castleproject/Castleproject.org-Site except there was no inline editor with preview, and HTML instead of a lighter markup language.

Of course, this means the maintainer has to review and merge every pull request for documentation, same as with pull requests with code.

gh-pages are the most flexible option, you can customize everything and create a better navigation, anyone can create pull requests, and you can bind it to a custom domain. But ultimately I chose loose markup files committed directly in the same branch as the code. This means that code and documentation go always together, and are branched and tagged together (i.e. better versioning). Also, I didn't like any of the available templates and it seems it has a higher maintenance cost (either you go the pure html way, which is more taxing for editors, or use Jekyll, which might fail ( https://help.github.com/articles/pages-don-t-build-unable-to-run-jekyll )).

Just my 0.02

Cheers,

Mauricio

--

Mauricio

--

You received this message because you are subscribed to the Google Groups "Castle Project Users" group.

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-u...@googlegroups.com.

[Aleš Roubíček]

Cool. With Jekyll it will be also possible to handle old URIs and host it on the castle domain.

--

Mauricio

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-users+unsub...@googlegroups.com.

[Krzysztof Kozmic]

you mean we could host it on github, with our old domain?

Or host Jekyll on Castle server?

-- 

Krzysztof Kozmic

To unsubscribe from this group and stop receiving emails from it, send an email to castle-project-u...@googlegroups.com.

[Aleš Roubíček]

GH Pages with Jekyll on custom domain