[infinispan-dev] docs moved

[Pete Muir]

Hi Sanne

I also feel that it already feels more like documentation - funny how just the feel of a tool changes it. I think we have a long way to go though, to make it as good as e.g. the Hibernate docs, or Weld docs. Things I have identified:

* make the layout and formatting consistent. There are many different header levels in use, different styles applied for defining terminology etc. I will write up a style guide for this next week, and also work through the existing docs and apply
* make the writing style, language and grammar consistent - at the moment the doc does feel like it's been written by 5 or 6 people, when it should feel like it's been written by one
* add more to the tutorials (and rename these to a Getting Started Guide), and add in more quickstart examples (this is something we are trying to improve JBoss wide, and I will probably be updating/adding the the main guidelines for JBoss)
* add more in the way of recommendations and "patterns" to the main user guide (and make this more of a reference guide) - I think with BigData this is especially important
* Organize the FAQs (we have a lot, possibly too many, some need moving into the user guide I expect)
* Integrate the "New in version XXX" into the main user guide, and add a "Since version XXX" to that page as needed (it's dreadful to make a user look in 5 places to understand what to do!)

Open questions I would like feedback on (there will be more!):

* Media (e.g. videos, podcasts). Currently these are collected on both the wiki and in the docs. I would like to collect them all on the wiki, but link to them from the docs as relevant. Do others agree?

On my TODO:

* Sort out how we do includes (I played with various approaches yesterday, I prefer to keep each chapter as one page, or multiple pages, and include onto the main page)
* Consistent style
* Update Wiki homepage to incude all examples

On 24 Jun 2011, at 22:51, Sanne Grinovero wrote:

> Hi Pete,
> very nice I'm liking it more than the previous docs, I guess the
> previous organizations was leaving on me a feel of "scattered notes"
> and generally unpolished.
> I've tried to change some pages to fix small rendering issues (nothing
> important nor urgent), but when I try to edit it I only get a white
> screen, like if there's not content at all.
> Especially this page:
> https://docs.jboss.org/author/display/ISPN/Querying+Infinispan

It's working fine for me (in Chrome). Have you tried the wiki markup tab?

> 
> Anybody else experiencing this?
> Never had such issues with confluence before, and also I can edit
> other pages properly.
> 
> One objection about the page "Developing the Infinispan Framework":
> can we remove "framework" ? While I'm not totally sure of what can be
> named like that, I don't think Infinispan is to be included in the
> category.

We can't just remove "Framework". Experience has taught (from Hibernate and Seam/Weld) that if you have a page/guide "Development of Infinispan" that most people will assume it is a guide about developing apps using Infinispan, not a guide about how to develop Infinispan itself. We found the best answer is to add something like Framework or Library to the title, as this clears up the ambiguity. If Infinispan is not a framework, what is it? (That's a real question, not rhetorical ;-).