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

[Martin Bless]

Hello everybody,
hi François,

I hope you're all having a good time. 

Note::

   This is a Request For Comments (RFC):
   If you have comments please let us know.
   NOW IS THE TIME!


==============================
T3DD12
==============================

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. :-)


==============================
Naming
==============================

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. So this is what we discussed and
agreed on:

The general scheme is:

{server} {product} {manual name} {language} {version}

Examples:

http://srv123.typo3.org /TYPO3/typoscript-reference/
http://srv123.typo3.org /TYPO3/typoscript-reference/4.4/
http://srv123.typo3.org /TYPO3/typoscript-reference/ru/4.5/
http://srv123.typo3.org /TYPO3/typoscript-reference/en_gb/4.5/
http://srv123.typo3.org /TYPO3/typoscript-reference/en_us/4.5/
http://srv123.typo3.org /TYPO3/security-guide/
http://srv123.typo3.org /TYPO3/security-tutorial/
http://srv123.typo3.org /TYPO3/extensions/
http://srv123.typo3.org /FLOW3/the-ultimative-guide-to-flow3/
http://srv123.typo3.org /PHOENIX/typoscript-reference/1.0/
http://srv123.typo3.org /TYPO3/documentation-template

We should be understandable to everyone as much as possible. So we
should avoid developer insider jargon in the URLs.

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/

This would point out very clear that its a preliminary 
version and teaches at the same time that the final version will be
   http://docs.typo3.org/

"TYPO3" as top level brand is represented by the domain name
"typo3.org".

Then its the product that follows: TYPO3, FLOW3, PHOENIX or whatever
there may be.

Everything after the product in the URL will be lower case only.

Next part ist the document name. It should closely follow the regular
title of the document and, where applicable, include the type of the
document: "abc-reference", "bcd-guide", "cde-tutorial", "def-howto".

If there is a translation of a document it can be reached by adding
the language code like /at/, /de/, /fr/, /ru/.

That means: All translations are using the same english lowercase
document name IN THE URL.

The language code may even turn into a localization code like /en_gb/,
/en_us/. Once we are using the translation server this is more
probable to happen.

The  'generic URL' of the document always leads to the current stable
version of the document. So today

    /TYPO3/typoscript-reference/

is pointing to the 4.6 version and soon it will point to the 4.7 
version of the documentation.

To refer to a specific version add the version number
to the URL as "number" "dot" "number": /1.0/, /4.6/, /6.0/, /10.15/

Version follows language if we have both.

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

Extensions shall be found following "/TYPO3/extensions/".

I suggest we put ALL extensions there no matter if they are a system
extension or not.


==============================
GIT names
==============================

My proposal:

/Docs/TYPO3/Reference/TyposcriptReference.git
/Docs/TYPO3/Reference/TyposcriptReferenceRu.git
/Docs/TYPO3/Reference/TyposcriptReferenceEnGb.git
/Docs/TYPO3/Reference/TyposcriptReferenceEnUs.git
/Docs/TYPO3/Guide/SecurityGuide.git
/Docs/TYPO3/Tutorial/SecurityTutorial.git
/Docs/FLOW3/Guide/TheUltimativeGuideToFlow3.git
/Docs/PHOENIX/Reference/TyposcriptReference.git
/Docs/TYPO3/General/DocumentationTemplate.git

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.


==============================
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..


==============================
URL parts of the document
==============================

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'.

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


==============================
Next team meeting
==============================

Thursday, 19th of April 2012, 21.00-22.00 CET.
Feel free to join and listen or comment.

http://bigbluebutton.typo3.org/bigbluebutton/typo3/start.jsp?action=invite&meetingID=Documentation+Team+Meeting


Turn over!

cu, Martin

PS: You're lucky - this posting is much shorter now. I had written it
before in the morning - until the SSD had a problem and made it vanish
in the haze. Arghh ...

-- 
http://mbless