[Typo3-documentation] Extension Documentation

[Ingmar Schlecht]

Hi Peter, hi DocTEAM!

Peter Kindström wrote:
> Wait a minute!

Sorry for not having asked the DocTeam first.

> I think the idea is good, but don't we just fill the wiki with 
> links to almost emtpy pages?

Interesting question, because I'm also prefering a clean wiki without 
many "stub" pages without much content.

> Will peolpe really start writing 
> documentation just because we give them access to a wiki page? 

Yes, they will, because they now know about how EASY it is to create 
documentation. If every extension has a link "Write documentation now" 
it is very inviting to just click the edit button and write something.

> Dont we risk giving lazy programmers an excuse: "don't complain 
> about no manual - write it yourself on the wiki !"

No, I don't think that's a big problem.
I think a wiki would even inspire the developer of the extension HIMSELF 
to write documentation.

Look at one of my documentations:
http://typo3.org/documentation/document-library/dkd_feuser_belogin/Tutorial-9/

I know that one is realy _bad_ but still, it is VERY helpful compared to 
no manual at all!

Take it as an example:
It took about 10minutes to write it, but the most annoying work was 
handling the SXW document:
  - uploading it to Typo3.org
  - configuring it for the TER
  - solving a little typo mistake
  - uploading it again
stuff like that...

If I had the option to just use the Wiki, I would have had to spend just 
10 minutes, nothing more.
If there was a spelling mistake in there, or something is unclear, 
anyone could improve it.

> My ideal is that every manual/page on the wiki should have a "
> main editor". 

The main editor for every extension documentation is the author of the 
extension. He is still responsible for bad documentation.

> The reason is that we then can have some control 
> over progress and content.

s.a.

> And we know that someone is 
> interesting in getting it done (or at least start it).

The extension author should be interested in that really.

> If we "automake" 30-40 pages without anyone "careing" about 
> them we risk ending up with 30-40 nearly empty pages with low 
> quality content.

We don't "automake" them!

http://wiki.typo3.org/index.php/AutomadePage

How would you call what I have just done?
Did I automake the page "AutomadePage"?

In my point of view, I didn't.

I just enabled someone who wants to create the page, to create it just 
clicking the link above and EDIT.

We just enable easy creation of a page, we don't create any empty 
records in the wiki database.

Someone still has to take the initiative to click the EDIT button and 
write some text.

> I think the wiki should be used for easy editing/adding of 
> content, but I think it would be good if people have to think a 
> little before adding a new wiki page! We dont want the wiki to 
> be a scribble board...

Actually, I disagreee.

In my point of view, a wiki page is very dynamic.

It is no problem if the page is bad in the beginning. It will sooner or 
later be edited by someone and improve.

Again, the example of my manual:
http://typo3.org/documentation/document-library/dkd_feuser_belogin/Tutorial-9/

I would call that "bad documentation". Better than nothing, though.

> Instead I think we should use this idea more selective.

I think it's the opposit.
We should use SXW documentation SELECTIVE, and use the Wiki for work in 
progress.
If a wiki page is good enough, it can be SELECTED and uploaded to Typo3.org.

> When 
> someone has started a wiki page for an extension, _then_ we add 
> a link to in from the TER.

This spoils the idea I had.
My thinking was "How do we get more people to using the Wiki instead of 
complaining about the no-existant Guestbook manual?".

The solution I saw was, putting a link "Create documentation now!" close 
to the "No documentation available." text.

> Then we know that someone cares 
> about the extension manual and not just adds an empty page.

s.a., the extension author is the ultimate supervisor of an extension 
manual.

> About the file name, isn't the pages filename also the name 
> viewed as the header of the page?

Yes.

> Would we like to have a page 
> named "Tx_jullegallerylib"?

We should turn off the feature of MediaWiki to capitalize the first 
letter of the page title.

> I think we should name pages like "
> Ext News",

The extension title is not unique, but the extension key is.

If Typo3.org automatically generates a link like "Ext News", it could 
point to an already existing page for a DIFFERENT extension.

I don't have anything against a page title "tt_news".
Then I'm at least sure the page is about "tt_news" and not any other 
news extension.

> "Ext General office displayer" and so on. Not use 
> the extension key (if it becomes the page header ).

OK, if you prefer that, we could do this as well...
We'd have to find a solution to the problem of two extensions with the 
same title.

OK, bottomline is:
  - About the pages filenames, I'm open for suggestions.
  - About the link "Create documentation" now, I would VERY MUCH
    like you to accept the idea.
But of course, I'm not a member of the DocTEAM so your opinion counts.

cheers,
Ingmar