[TYPO3-doc] After the T3DD12: The plan for the URLs - please check!

[François Suter]

Hi Martin,

> The devdays have been very encouraging I would say. We got lots of
> positive feedback, ran into open doors everywhere, got some people
> going and had fruitful discussions. :-)

That's very good to hear :-)

> The naming issue became very easy to solve once we found out that we
> have to look at it from a different perspective: The URLs are of first
> priority and not some internal keys.

I think this makes a lot of sense.

> We'll be starting with a server name that clearly indicates that its
> a temporary solution. Currently we have "srv123.typo3.org". The more
> I think about it I find "preliminary" much clearer:
>     http://preliminary.docs.typo3.org/

I think that "preliminary" is really too hard to type. It may be a 
temporary name, but still. Why not just go for "temp".

> We did not talk about this: We need a symbolic version number to
> address the upcoming version - what used to be "trunk". My suggestion:
> "future-version":
>
>     /TYPO3/typoscript-reference/future-version

What about "nightly". I had been thinking about this for a long time: if 
the rendering process is not too costly, we could render the official 
documentation (and *only* the official documentation, not extension 
manuals) on a daily basis, thus providing a nightly build.

> Extensions shall be found following "/TYPO3/extensions/".
>
> I suggest we put ALL extensions there no matter if they are a system
> extension or not.

That makes sense at least from the point of view of URLs. As far as 
index pages are concerned, we'll have to think of a way of setting 
system extensions apart.

> /Docs/TYPO3/Reference/TyposcriptReference.git
> [snip]
>
> Rationale:
> "/Docs" like in the URL
> "/TYPO3" = product
> "/Guide", "/General", ... = mandatory part indicating the type
> "/TyposcriptReference.git" = keeping the document name.
> Using camel case because all GIT names are made like this.

What about "Documentation" instead of "Docs" like the existing Doc Team 
project?

> ==============================
> Internal key names
> ==============================
>
> In short for the insiders: We found out that we are more flexible
> here. We have to think of a clear naming scheme in the context of the
> URLs as delineated above. The context of the keys we use for
> crossreferencing is much smaller as these keys can independently
> define in the document where they are being used..

I agree.

> I will improve the reST splitter so that we will have meaningful names
> in the URL only. This will eliminate the currently irritating numbers
> like '01-01-Introduction'.

Great!

> Currently some files = pages are too short, others are too long. This
> is something we can only correct manually as it depends on content.

Absolutely.

Cheers

-- 

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