[TYPO3-doc] Domain model for documentation

[Robert Lemke]

Hi François,

On 27.07.2012, at 16:12, François Suter <fsu-lists at cobweb.ch> wrote:

> As you know if you follow this list regularly (and read the meeting minutes), Fabien has been making progress with the FLOW3 application that will drive the documentation rendering and display (roughly said).
> 
> As this is really experimental for now, Fabien has been using a Github repository. We'll move to the TYPO3 Git repository when we're closer to something stable.

great!

> 1) first and foremost, Fabien created a model called "Documentation", which represents one version of one manual for one extension/package. I would propose to call this model "Manual" instead, because it fits the domain better IMO. In particular "Documentation" is a mass noun, which means it is not supposed to be plural, so we're not supposed to have methods like "getDocumentations()". Any opposition?

How about "Document"? We could then have different kinds of documents (designated by a type field) and one of the could be "Manual".

> 2) about the version number field: do we want to be fully open about this or should we validate it agains an "x.y.z" schema?

I think a version parseable by version_compare() (http://php.net/version_compare) would be helpful. But on the other hand we could also completely go without a version field and just use a timestamp. What would be interesting in the future is some way to relate the document to a package ("applies to FLOW3 version x").

> 3) about the language, same question: should we validate it against a "xx_YY" schema?

yes, must be a valid locale.

> 4) more importantly, how about the handling of authors? In the version I committed I created a many-to-many relation to Persons (as in \TYPO3\Party\Domain\Model\Person). This model has a name and an e-mail address, but not more. Do we want to extend this with an Author model? The advantage is that it could be related to a company (another Party) and have a reversed relation to the manuals, so that you could actually look up all the manuals a person has worked on. What do you think?

Yes, I think creating an Author class as subclass of Person would make sense.

Cheers,
Robert