[TYPO3-doc] DocBook: storage structure

[François Suter]

Hi all,

Following up on the first discussion about structure and processes, 
which brought a lot of information about rendering and structuring in 
sets, in particular, I have started thinking about how the documentation 
repository could look like.

Here's a first sketch (comments below):

.
├── FLOW3
│   ├── Core
│   └── Packages
├── TYPO3v4
│   ├── Books
│   │   └── ExtbaseFluid
│   ├── CoreManuals
│   │   ├── doc_core_api
│   │   │   ├── de
│   │   │   ├── en
│   │   │   │   ├── chapter1.xml
│   │   │   │   ├── chapter2.xml
│   │   │   │   ├── images
│   │   │   │   ├── index.xml
│   │   │   │   └── preface.xml
│   │   │   ├── fr
│   │   │   └── ru
│   │   ├── doc_core_cgl
│   │   ├── doc_core_inside
│   │   ├── doc_core_services
│   │   ├── doc_core_skinning
│   │   ├── doc_core_tca
│   │   ├── doc_core_ts
│   │   ├── doc_core_tsconfig
│   │   ├── doc_core_tsref
│   │   ├── examples
│   │   └── set.xml
│   ├── Extensions
│   ├── Guides
│   │   ├── doc_guide_install
│   │   └── doc_guide_l10n
│   ├── SystemExtensions
│   │   ├── felogin
│   │   ├── rtehtmlarea
│   │   ├── set.xml
│   │   └── workspaces
│   ├── Tutorials
│   │   ├── doc_tut_quickstart
│   │   └── doc_tut_ts45
│   └── fullset.xml
└── TYPO3v5
     ├── Core
     └── Packages

I have gone into more details inside the "TYPO3v4" branch, as this is 
where we have the most stuff yet. On top of the 3 main categories (Core 
manuals, Guides and Tutorials), I have added a subfolder for all 
extension manuals, one for books (like the Extbase and Fluid book) and 
one for system extensions.

The thing with books is just an idea. One could argue that they can fit 
into some of the main categories (most likely guides), but OTOH I think 
it's good to keep books apart, as they don't represent official manuals.

As for system extensions I think this is a real opportunity to finally 
have those manuals in the same place as the others. I would say that we 
should actually move them entirely out of the Core source code. The 
Extension Manager could be modified to point to online versions or 
downloads, just like for other manuals. Those manuals would finally be 
available online too, and it would give them more visibility regarding 
their maintenance.

I have placed a "fullset.xml" file at the root of the "TYPO3v4" folder. 
It's about having a kind of "super-set" which groups all manuals from 
the 3 main categories. I'm unsure yet whether this is a good idea or 
not. I think it's better for cross-linking, but maybe not (the 
cross-linking stuff is still not entirely clear in my head).

Anyway I would imagine having at least a set for each of the 3 main 
categories and probably also a set for all system extensions manuals. As 
discussed in the earlier thread, I don't think it's a good idea to have 
a set for all extensions, as there are just too many. As books are 
stand-alone projects, I wouldn't expect to make a set for them either.

Let the discussion start! :-)

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch