[TYPO3-core] How to refer to TYPO3_CONF_VARS in the documentation (since v6.0)

[Ernesto Baschny [cron IT]]

Hi,

François Suter schrieb am 06.12.2012 15:52:

>> Wasn't it the plan some time ago to split up "Inside TYPO3" into
>> separate documents to avoid having a "huge package" which needs to be
>> "updated at once"? Having a separate document per "chapter" would allow
>> to release new chapters faster and developers will be able to identify
>> which section is how old more easily. We could start doing that with
>> "new chapters" (like this "LocalConfiguration" documentation) to avoid a
>> huge overhead.

> I don't think this was ever planned. Some things made sense like
> extracting TCA reference from Core API and some other areas had need for
> such extension documentation (e.g. skinning or FAL) as to warrant their
> own manuals, but I think splitting the manuals too much would make
> information even harder to find.

For the user it's important to know what's the "last update" date of a
chapter, so if they are not split up, at least the "last update"
information should be added to every chapter.

For me finding the information won't get less confusing if it's not "one
huge manual" anymore but instead where "each chapter is a manual".
Nobody (I think) reads the whole "Core TYPO3 API" from start to bottom.
It's used as a reference, you jump in at the chapter you want to know
more about.

Releasing the separate chapters as "separate manuals" would have several
benefits for the doc-team and for the public (in my eyes):

- you (as the doc team) don't need to "do a full review" of a huge
document to make a new release. Just re-release a new chapter once it's
ready. Think about t3lib_mail API, LocalConfiguration documentation,
etc.. So much pending stuff just because noone dares to fully review the
huge "TYPO3 Core API" document. It's a tough decision to release a new
version of it.

- we (as a doc reader) can more easily follow "new documentation"
snippets if they are released in smaller chunks. You can announce that
separately ("New documentation on the Caching Framework is avaliable at
doc_core_api_caching" etc.).

- we (as a doc reader) can at one glance see when a chapter was written
and thus estimate if the information is "old school information" or "new
information". No need to constantly re-view old sections to see if they
are still up-to-date as a whole. Each chapter stands by itself and has
it's reason to exist (and maybe cease to exist). It's very difficult to
do that on a huge document which a mix of information from different
TYPO3 generations.

> Furthermore with the move to ReST, splitting documents is not as
> important as when we used OpenOffice, where large files were really
> unwieldy. With ReST one can work on a single chapter at a time and we
> release continuously. Of course that involves keeping people informed of
> which chapter was updated and is something we need to think about. My
> current worry would be rather to find a general way of marking out of
> date sections.
>
> That being said, maybe there are reasons to split Inside TYPO3.
> Reviewing it after all these years is definitely an opportunity to keep
> an eye open for this.

Introducing and removing sub-documents like I propose above should be
"easy" and unbureaucratic (no new forge projects, no new git
repositories). Maybe keeping the central document as a "glue" pointing
to the separate documents. It might also be just a matter of giving more
"structure" to the current "list of Core Documentation" [1]

Just some ideas. I would love to get more involved in contributing to
the documentation (my programming skills are getting more and more
rusty, but I still can write). :) Maybe I could join a next
doc-team-meeting as a by-stander? I am sure you have discussed stuff
like that before and I don't to interfere in a potentially working and
well thought master-plan, just want to help a bit where I can (maybe
with the current view of an out stander).

Cheers,
Ernesto



[1]
http://typo3.org/documentation/document-library/core-documentation//current/