[TYPO3-doc] Domain model for documentation

[François Suter]

Hi Jacob,

> Versioning the manuals is great. I suspect the manual would have its own
> versions and not follow the TYPO3 version-scheme, right?
> That way we can say that v2.5.3 of the TSRef applies to TYPO3 4.5-4.7 and
> v3.5.3 applies to TYPO3 6.0 or some such.
>
> Or would we want some other scheme that is intertwined with the TYPO3
> version number?

We do that for part of the official TYPO3 documentation. Manuals like 
TSref, TSconfig, TCA reference, Core APIs, Inside TYPO3 all follow the 
TYPO3 version numbers. With a catch: since they are currently packaged 
in extensions, we are obliged to raise the version number when releasing 
them again (for example after corrections). So while the TSref for TYPO3 
4.5 was originally numbered 4.5.0 we had a 4.5.1 a while later, and in 
the meantime TYPO3 4.5 went on to have many bugfix releases and is now 
at 4.5.17.

> With the FLOW3 docs, the docs are stored in the TYPO3.FLOW3 repo, and so
> they're sort-of relatable to a specific version of FLOW3, but as we write
> new chapters they often also apply to previous versions of FLOW3. How do we
> deal with that?
>
> Does the domain model need some kind of metadata-attribute for the range of
> versions that a document applies to?

You're right that we may need some more detailed information than just a 
version number. But does that really belong to meta data? What we have 
been doing so far with the TYPO3 documentation is to indicate 
"compatibility" in an introductory paragraph. Furthermore - in recent 
updates - we have started taking care of always writing down from which 
version a given feature/property/API was available. I think this is 
actually more useful.

If I take the TSref as an example, we are planning to take advantage of 
the migration to ReST to restructure the TS properties description and 
include TYPO3 versions range to them. This way we could even do without 
keeping separate versions IMO, except if we want to start removing 
properties that were deprecated and removed several versions ago.

In this sense it is true that Robert's point of keeping just a date/time 
may be enough. OTOH I think it's important for extension manuals to keep 
version numbers. So I would say we need to keep versions, but it's not 
necessary that they are coupled to their related product's version 
scheme, as some currently are. Furthermore I would rather not add 
additional meta data, but rather have a mandatory paragraph - at least 
for official manuals - that defines which versions of the product are 
covered in the given version of the manual.

Cheers

-- 

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