Difference between revisions of "Talk:Organization of the documentation"

Latest revision as of 08:55, 14 December 2006

First proposal

I propose to organize the documentation this way

Here is an example :

Adempiere 3.1.1 : main entry, here you will have your Table of contents and an introduction

The Chapters :

• Adempiere 3.1.1/Chapter1 : Category : Adempiere 3.1.1
• Adempiere 3.1.1/Chapter2 : Category : Adempiere 3.1.1
• Adempiere 3.1.1/Chapter3 : Category : Adempiere 3.1.1

Note the "/" you can do that in Mediawiki by creating creating "Chapter1" inside "Adempiere 3.1.1" and putting a / before like this /Chapter1

In a second time maybe we can do something the way its done in Wikbooks

See http://en.wikibooks.org/wiki/Java_Programming for an example;

--Khalid HASSANI 06:40, 16 November 2006 (EST)

Hi Khalid,

I understand your poposal. My question is: when we need to add the documentation for the Adempiere 3.2.0 we must do something like:

Adempiere 3.2.0 : main entry, here you will have your Table of contents and an introduction

The Chapters :

• Adempiere 3.2.0/Chapter1 : Category : Adempiere 3.2.0
• Adempiere 3.2.0/Chapter2 : Category : Adempiere 3.2.0
• Adempiere 3.2.0/Chapter3 : Category : Adempiere 3.2.0

On this way we preserve the 3.1.1 documentation. Is correct thus?

Alejandro Falcone

Hi Alejandro,

indeed you are correct with your assumption, *Adempiere 3.2.0/Chapter1 will become a chapter1 article in the ADempiere 3.2.0, however the category does not be include in the title of each chapter, categorization on mediawiki is done by wikimarkup. So a simple [[Category:ADempiere3.2.0]] at the bottom of the manual pages. --Goanookie 08:45, 16 November 2006 (EST)

Yes Alejandro, that was exactly what I was meaning

--Khalid HASSANI 10:09, 16 November 2006 (EST)

wikiprojects or namespaces

If the current progress of ADempiere keeps going, we should think a bit further then just organization of the documentation. For the moment the wiki contains multiple languages en fr es de and I assume more will follow, and this will become unmanageable in the future. for the moment I don't think it is necessary to setup separate wikis for different languages, but I'm still keeping that option open.

User:Khalid HASSANI already suggested of using wikiprojects (the '/') but we could go one step further and use mediawiki namespaces, using those will also have the benefit that each namespace can be searched separate from other pages. In any case if we want to generate a pdf manual of the documentation, the manual pages have to be in a wikiproject, makes the script to generate the pdf a lot easier also. And no need to keep track of the changes in the manual, script will always be capable of generating the pdf.

--Goanookie 08:38, 16 November 2006 (EST)

Hi Peter,

Sound very interesting your proposal. How do you think that we could use the namespaces? I mean, by Adempiere version, by language or any other form?

--Alejandro 11:46, 16 November 2006 (GTM -03)

Hi peter, yes indeed namespaces have the advantage of making documentation searchable separately, sounds a good proposal for me.

--Khalid HASSANI 10:07, 16 November 2006 (EST)

Recovered from google cache - Thanks Google !!! :)

More documentation organizing talk

Ok i m back, and i got things to discuss. First.. our manuals are growing in types such as Technical (Carlos/Alejandro), User (Implementation - IDALICA), and others such as HowTos, Tutorials. So to better organise i suggest that we first have a separate MANUALS page. Main page just link to it. This also helps make the front page more brisk. And the www.adempiere.org page merely has to link to that one manual list page. U think? anyway i notice that the Categorization is already a big help and this note of mine may be off the mark

Red1 18:24, 26 November 2006 (EST)

Hi Red1,

Yes, I agree. Maybe a Documentation Page and divide the page in sections as: Technical Manuals, User Manuals, HowTos, Tutorials, etc. Could be good to know what think about this Khalid the biggest expert in wiki.

Alejandro Falcone 14:42, 27 November 2006 (GTM -03:00)

Thanks Aljandro for the nice words :) your sections seem good, although my question is should we use the term Technical Manuals or Developer documentation instead ? or both if those are two different things and what do they mean ?. Another thing that should be nice to have now that we are starting Manuals in different languages is how to organise this, and make from a language to an other a breeze, there is a nice idea here : http://www.mediawiki.org/wiki/Help:Contents we can borrow, this is convenient as the languages will be closely related and transaltions can be done easily. --Khalid HASSANI 14:23, 27 November 2006 (EST)

Hi Khalid. I think that the documentation that we have under Manual is Technical Documentation. I understand that Developer Documentation is something as Tutorials or Hacker's_guide. If you agree with this, I can change the scripts to generate the wiki pages to add the category Technical Documentation and then generate the new content for the ADempiere 3.1.1 version with the new category. What do you think?

About your proposal for the Manuals in different languages, i believe that is a very good idea. I think that this way can help us to organize and centralize the documentation, and we can give a easy way to access to it. -- Alejandro Falcone 17:31, 27 November 2006 (GTM -03:00)

All these sounds marvelous! If no issue go ahead and try. Then we see :D 18:45, 27 November 2006 (EST)

Maybe we can try somethinhg like this -- Red1

Ok Aljandro. For me, Technical manual is all what is not User manuel :) they are complementary as they say in Mathematics. In the first case the public intended is : Developers, Installers, Admin, etc, in the second case it's the end user; although sometimes we might have an overlap between them, but categories handle this quite well. While you are at it, could you also add a /en for the English documentation and /es for the Spanish and so on, like in this page : http://www.mediawiki.org/wiki/Help:Tracking_changes/fr.

We also said that we will have a specific namespace for manual ? so let it be help then; help is more general than manual, as it can contains manual, faq, tutorials in the same time and this is something people look for spontaneously. The categories will have a /en and /es in them but they will be in the main namespace, when you are finished I can then import the language templates and voila :).

If everybody is Ok, I'll write synthesis on the main page i.e Organizing the documentation of what is going to be done and by whome. Lets make it a kind of small school case a first experiment in the decision process inside the community.

Last not least don't forget to add this page to your watchlist, you will notice new input easier.

--Khalid HASSANI 07:49, 28 November 2006 (EST)

Hi Khalid,

Now the script generate the files, with the page content, with a name as:

ManPageW_BusinessPartner.wiki for english language

ManPageW_BusinessPartner_es.wiki for spanish language

ManPageW_BusinessPartner_ru.wiki for russian language

then we use WWW::Mediawiki::Client for upload those files to our wiki site.

But in order to organize into namespaces we should name those files as:

ManPageW_BusinessPartner.wiki for english language

ManPageW_BusinessPartner/es.wiki for spanish language

ManPageW_BusinessPartner/ru.wiki for russian language

but the problem is that those names are not permited (by '/' ).

Do you have any idea about how can we resolve the problem? The '/' is the only way to use namespaces?. Thanks for your continuos support!

-- Alejandro Falcone 11:15, 28 November 2006 (GTM -03:00)

No Alejandro here the "/" is just a convention used to seperate the Entry name from the language it's similar to the "_", it dosen't have anything to do with the namespace, if you can't add the "/" then the "_" is still ok. Importing in a specific namespace is an other matter, you should see how this is done in WWW::Mediawiki::Client. One more thing, I don't unerstand why you added .wiki to the files ? is this done by the import software ? Please don't import anything yet, lets formalise the structure first in the entry page, see what I have already done there.--Khalid HASSANI 11:06, 28 November 2006 (EST)

Perfect Khalil, then we can use "_" without problem. The .wiki extension is required by WWW::Mediawiki::Client to upload the files into the wiki. Carlos is who use this tool to upload the files (he is on vacation at this moment by some days). I was who builded the script to generate the files. I will take a look in the tool page for the namespace issue with the tool, but i believe that the documentation is very poor there, maybe they need a wiki to do it :). And ok, we don't import any file until the structure is defined.

-- Alejandro Falcone 15:05, 28 November 2006 (GTM -03:00)

PDF generation

Lets put here your thoughts about the best way, tools, and organization to automatically generate pdf from the Wiki, how to generate pagination, table of contents and so on, some tools do exist, lets search for the best tool.--Khalid HASSANI 07:16, 28 November 2006 (EST)

I had already looked in the various ways possible to generate a pdf manual of the wiki articles, but since it is far from complete, and for the moment not very high priority. However, I'm trying out various wiki2pdf generators, I have already sort of found one which is pretty decent, and the pdf manual it creates is good, but that depends on the layout and the structure. I do have to check out if we can use categories also to select articles for pdf creation. In any case it will be mandatory that the manual pages are put in separate wikiprojects.--Goanookie 17:25, 1 December 2006 (EST)

Structure of the manual

About the structure of the manual, the current proposal is just a template to be used, so time to move on and start working on the structure on the manual. Having almost (still150 pages to go) read the compiere manual, which structure isn't the brighest one imho. And their lack of a decent technical manual also. We should have besides different language versions,

   * an end-user manual
   * an installation manual
   * a configuration manual
   * a technical reference manual 

I will start a new topic on this article but I have to do some paperwork before it, and consult a few of my technical manuals, comparing structure and such. --Goanookie 17:25, 1 December 2006 (EST)