[TYPO3-doc] @all teams: Important! Please help: How to map Git paths to urls?

[Martin Bless]

Hi, 

my points are:

- we have to take the rebranding into account

- I'd like to have real database table that stores the mapping we
(will) have agreed on. Until now these mappings are hidden
somewhere in some shell script or Makefile files, which is bad.

- We will need that mapping table anyway once we actually start
dispatching build jobs to the task queue

- I'd like to have a comprehensive picture of ALL stuff we want to
present in the docs (neos, surf, flow, ...)

>I would not use "typo3cms" as we already have "typo3" in the domain 
>name. I would use "cms", because that's what the product name is, 
>strictly speaking.

We should keep in mind that <domain> and <pathToManual> should be
thought of as being separate in a way:

(1) We are planning to mirror <pathToManual> at typo3.org,
starting at some subpath. So we'll have (at least):
http://typo3.org/docs/<pathToManual>

.. note::

   It wouldn't hurt at all, if we already knew what the subpath
   for documentation on typo3.org will be as it has something
   to do with the "asthetics of urls" as well.

   Will it be http://typo3.org/docs/ ???


(2) We will probably ofte refer to a manual by just citing the
path. And if that's only "/cms/OfficialManualExample/" you have no
idea that it belongs to our - still main product - TYPO3 any more.

(3) I take that "strictly speaking" of yours in the quote as proof
that you don't make that natural and automatic translation in your
brain that "cms" actually should be read as "TYPO3 cms".

(4)
[nasting ranting ON]
Would Nivea Cream call it's Cream just "Cream"? Would Coca Cola
call it's drink just "drink"? Why the hell should we call our main
product that is the main reason we have such a strong brand
"TYPO3" just call "cms"?
[nasting ranting OFF]

(5)
The "typo3" in the domain is ambigious as it stands for the TYPO3
family brand name now. Strictly speaking, it's standing for the
family brand only. And I really dislike the idea that you have to
do a lot of thinking to recognize that that "cms" you're seeing
there actually ist the indication for "typo3cms", which is what
you're looking for. Usability: Don't make me think!

Considering (1) to (5) I'd really like to see "typo3cms" there. So
we might come up with:
http://typo3.org/docs/typo3cms/CoreApiReference/

and so on.

- I'm not sure if it has to be /docs/typo3flow/... as flow, surf,
neos and so on don't collide that much with the TYPO3 as family
brand name.


>> FLOW3/Packages/TYPO3.FLOW3.git/Documentation,
>> docs.typo3.org/typo3flow/typo3/flow/
>
>OK, so we have an issue here. What we see is that the names of the Flow 
>repositories are far more consistent, since the already include a 
>namespace hierarchy. IMO the above URL looks terrible, because of the 
>redundancies of words. But of course since "flow" is the product and 
>also the name of base package containing the documentation, we have a 
>duplicate anyway. At the very least, we should drop "TYPO3" when it is 
>the first "segment" of the repo's namespace. And use just "flow" for the 
>product name. This means we would have URLs like:
>
>docs.typo3.org/flow/flow/
>
>This doesn't look great either, but I don't know how we can avoid that. 
>Maybe by deciding to use "packages" since all Flow code is wrapped in 
>packages. So we could have:
>
>docs.typo3.org/flow/package/flow/
>
>It would be good to have the Flow team's point of view on this issue.

Indeed, as I must say that I don't have the knowledge for this
kind of thing.


- And now, once again after the rebranding and with the upcoming
6.0 release in mind, let's think about upper and lower case once
again. Will we only have lower case until we reach the crucial
part, that is the actual manual?

(A)
http://typo3.org/docs/typo3cms/extensions/news
http://typo3.org/docs/typo3cms/CoreApiReference/
http://typo3.org/docs/flow/package/flow/


In summary:
* I strongly vote for having "typo3cms" instead of only "cms".
* I like (A).
* I'd like all of us to agree on a concrete mapping table.

Sail on ...

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de