You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lenya.apache.org by Thorsten Scherler <th...@juntadeandalucia.es> on 2004/06/01 13:07:15 UTC

[Documentation] Refactoring docu

Hello devs,

The http://issues.apache.org/bugzilla/show_bug.cgi?id=29032 is right now 
only talking about the forrest build process but the docs need a *mayor* 
refactoring about how they are organized!
I think we have to restructure them heaps!!!

Have a look at e.g. http://jakarta.apache.org/struts/userGuide/index.html.
For me that is an example how to structure a good documentation.

For us that would mean divide the existing docs into following 
categories (e.g.):
*user guide*
-Tutorials and How-Tos-wiki ...
--FAQ
--...
-Editors
---HTML Form Editor
---HTML One Form- developer guide
...

*developer guide*
-Architecture
...
-API
...

With existing docs I also refer to the wiki pages that we reckon are 
worth to integrate into the docu. This means we have to review the 
wiki-canidates.

WDYT?

King regards
thorsten

-- 
Thorsten Scherler

Departamento de Desarrollo de Proyectos
Sociedad Andaluza para el Desarrollo de la Sociedad de la Información S.A.U.
Avda. de la Arboleda s/n
41940 - Tomares,  (Sevilla)
Tlfn: (+34) 955 062 627
e-mail: thorsten.scherler.ext@juntadeandalucia.es

Este correo electrónico y, en su caso, cualquier fichero anexo al mismo,
contiene información de carácter confidencial exclusivamente dirigida a su
destinatario o destinatarios. Queda prohibida su divulgación, copia o
distribución a terceros sin la previa autorización escrita de "Sociedad
Andaluza para el Desarrollo de la Sociedad de la Información, S.A.U.". Si no
es Ud. el destinatario del mensaje le ruego lo destruya sin hacer copia
digital o física, comunicando a Sociedad Andaluza para el Desarrollo de la
Sociedad de la Información S.A.U. vía e-mail o fax la recepción del presente
mensaje. Toda declaración de voluntad contenida deberá ser tenida por no
producida. Gracias.
____________________________________________________________________________
___________________

The information in this e-mail and in any attachments is confidential and
solely for the attention and use of the named addressee(s). You are hereby
notified that any dissemination, distribution or copy of this communication
is prohibited without the prior written consent of "Sociedad Andaluza para
el Desarrollo de la Sociedad de la Información, S.A.U.". If you are not the
formal receiver of this message please destroy it without making any digital
or physical copy and inform "Sociedad Andaluza para el Desarrollo de la
Sociedad de la Información S.A.U." , by e-mail or fax, of the reception of
the present message. Any whatsoever involuntary declaration contained
herewith must be taken as having no legal effect. Thank you.



---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org


[RT] DOCO (Re: [Documentation] Refactoring docu)

Posted by "Scherler, Thorsten" <th...@apache.org>.
Michael Wechner wrote:
> I think we should add a "User Guide" node to the documentation, because 
> it seems
> to me that people would start contributing, especially it seems to me 
> that you
> in particular would like to add content in such a section, which would 
> be good start :-)
> 
> Mihci
:)

Bingo! ;-)

I really like that DOCO idea! User can help to enhance the docu and 
committer can apply by reviewing the changes. That seems to be rapid 
documentation ;-). For 1 language this seems to be quit awesome, but for 
x languages it is really going through the roof ;-).

...and yes I will do my part in asking you (and others) the questions 
that I have regarding concepts and technics and keep record of the 
answers in form of writting them down. I will add them to the lenya doco 
(in the future, and for now: documentation) site and user can ask me 
(and others) what they do not understand. *If* it is possible for the 
user to say *thank you* for the help, by enchance my docu (in the 
future, and for now: documentation) article would that be perfect.

Now lets talk about the translation of that doco-article. I may 
contribute a translation to spanish/german but I could not do that in 
all languages ;-). The other point is that my german translation would 
be one from a native speaker, the spanish one not. So if a native 
speaker could enhance my translation or translate the article in a 
different language we will have parts of the documentation in different 
languages. If somebody want to help he can try to translate an article 
into their native languages.

...and by doing this the user becomes as well active part of the 
project. I think that will make new committers, because (s)he can 
contribute on a regular basic. This is one criteria to become a 
committer. I had the honour to become committer for this reason (...do 
you remember ;-))

The thing is all the above mentioned should be *EASY*. For the user and 
the committer. It should be controlled by an integrated workflow. Lenya 
can provide the framework for that.

...and to be a help in DOCO the best way for me seems to feel 
responsable for our documentation. I think I will figure out where a 
user and/or dev (e.g. me) can have problems to understand the 
documentation. I will then hopefully as well figure out what the best 
way is to solve the problem to easily commit to the documentation.

The first thing would be the to refactor the docu. I am used to read 
scientific books. They are hardly structured in a loose descriptions of 
components. They are normally going from easy to hard, from basic to 
advanced. I am totally missing that by our documentation and I guess I 
am not the only one.

The next steps are in my eyes:
1) integrate the export to static html/pdf and different server.
I am working on that by the forrest refactoring. I will have to look 
closer into the forrestbot after finishing our skin.

2) integrate lenyas edit, workflow, roles functionality
That should not be so hard ;-). Basicly we need a form editor and a 
workflow. So it a simple question of getting started.

3) integrate notification system to the workflow
I dunno see any problem with that either. One can use an existing 
mail-server or SMS-Gateway.

King regards
thorsten
-- 
<thorsten>
  <name>Thorsten Scherler</name>
  <country>Spain</country>
  <@m...@mail>
 
<@c...@cocoon-WIKI>
  <http>http://www.target-x.de</http>
  <motto>
	"My task which I am trying to achieve is,
	by the power of the written word,
	[...] to make you see."
	*Joseph Conrad (1857-1924)*
  </motto>
</thorsten>



---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org


Re: [Documentation] Refactoring docu

Posted by Michael Wechner <mi...@wyona.com>.
Thorsten Scherler wrote:

>
>
> sorry I do not understand that mail?
>
> Can you explain to me what your point is on that topic.


I think we should add a "User Guide" node to the documentation, because 
it seems
to me that people would start contributing, especially it seems to me 
that you
in particular would like to add content in such a section, which would 
be good start :-)

Mihci

>
> ...and the snippet is not from gregors RE to this thread, or is it?
>
> King regards
> thorsten
>


-- 
Michael Wechner
Wyona Inc.  -   Open Source Content Management   -   Apache Lenya
http://www.wyona.com              http://cocoon.apache.org/lenya/
michael.wechner@wyona.com                        michi@apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org


Re: [Documentation] Refactoring docu

Posted by Thorsten Scherler <th...@juntadeandalucia.es>.
Michael Wechner wrote:

>
>>
>> -1 on having TO BE DONE all over the place. we had that before and it 
>> didnt work well
>
>
>
> this is not to be done, but rather there *is* as Thorsten is pointing out
>
>>
>>
>
>
Hi Michi,

sorry I do not understand that mail?

Can you explain to me what your point is on that topic.

...and the snippet is not from gregors RE to this thread, or is it?

King regards
thorsten

-- 
Thorsten Scherler

Departamento de Desarrollo de Proyectos
Sociedad Andaluza para el Desarrollo de la Sociedad de la Información S.A.U.
Avda. de la Arboleda s/n
41940 - Tomares,  (Sevilla)
Tlfn: (+34) 955 062 627
e-mail: thorsten.scherler.ext@juntadeandalucia.es

Este correo electrónico y, en su caso, cualquier fichero anexo al mismo,
contiene información de carácter confidencial exclusivamente dirigida a su
destinatario o destinatarios. Queda prohibida su divulgación, copia o
distribución a terceros sin la previa autorización escrita de "Sociedad
Andaluza para el Desarrollo de la Sociedad de la Información, S.A.U.". Si no
es Ud. el destinatario del mensaje le ruego lo destruya sin hacer copia
digital o física, comunicando a Sociedad Andaluza para el Desarrollo de la
Sociedad de la Información S.A.U. vía e-mail o fax la recepción del presente
mensaje. Toda declaración de voluntad contenida deberá ser tenida por no
producida. Gracias.
____________________________________________________________________________
___________________

The information in this e-mail and in any attachments is confidential and
solely for the attention and use of the named addressee(s). You are hereby
notified that any dissemination, distribution or copy of this communication
is prohibited without the prior written consent of "Sociedad Andaluza para
el Desarrollo de la Sociedad de la Información, S.A.U.". If you are not the
formal receiver of this message please destroy it without making any digital
or physical copy and inform "Sociedad Andaluza para el Desarrollo de la
Sociedad de la Información S.A.U." , by e-mail or fax, of the reception of
the present message. Any whatsoever involuntary declaration contained
herewith must be taken as having no legal effect. Thank you.


---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org


Re: [Documentation] Refactoring docu

Posted by Michael Wechner <mi...@wyona.com>.
>
> -1 on having TO BE DONE all over the place. we had that before and it 
> didnt work well


this is not to be done, but rather there *is* as Thorsten is pointing out

>
>


-- 
Michael Wechner
Wyona Inc.  -   Open Source Content Management   -   Apache Lenya
http://www.wyona.com              http://cocoon.apache.org/lenya/
michael.wechner@wyona.com                        michi@apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org


Re: [Documentation] Refactoring docu

Posted by "Gregor J. Rothfuss" <gr...@apache.org>.
Michael Wechner wrote:

> well, I think it's just about inserting the top level "User Guide" node 
> and I think
> we should this (actually there was one), because then people at least know
> where they have to add their documentation re users.

-1 on having TO BE DONE all over the place. we had that before and it 
didnt work well


-- 
Gregor J. Rothfuss
Wyona Inc.  -   Open Source Content Management   -   Apache Lenya
http://wyona.com                   http://cocoon.apache.org/lenya
gregor.rothfuss@wyona.com                       gregor@apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org


Re: [Documentation] Refactoring docu

Posted by Michael Wechner <mi...@wyona.com>.
Gregor J. Rothfuss wrote:

>
> this is an age old discussion :) we have re arranged the structure a 
> couple times by now. unless there is enough documentation content to 
> justfiy it i am -1 for restucturing.


well, I think it's just about inserting the top level "User Guide" node 
and I think
we should this (actually there was one), because then people at least know
where they have to add their documentation re users.

Michi


-- 
Michael Wechner
Wyona Inc.  -   Open Source Content Management   -   Apache Lenya
http://www.wyona.com              http://cocoon.apache.org/lenya/
michael.wechner@wyona.com                        michi@apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org


Re: [Documentation] Refactoring docu

Posted by Thorsten Scherler <th...@juntadeandalucia.es>.
Gregor J. Rothfuss wrote:

> Thorsten Scherler wrote:
>
>> For us that would mean divide the existing docs into following 
>> categories (e.g.):
>> *user guide*
>> -Tutorials and How-Tos-wiki ...
>> --FAQ
>> --...
>> -Editors
>> ---HTML Form Editor
>> ---HTML One Form- developer guide
>> ...
>>
>> *developer guide*
>> -Architecture
>> ...
>> -API
>> ...
>
>
> this is an age old discussion :) 


I know we had that back in the wyona-dev list as well, but documentation 
discussion never get old ;-)

> we have re arranged the structure a couple times by now. unless there 
> is enough documentation content to justfiy it i am -1 for restucturing.
>

It is not only to arrange the structure but also to lead the user a wee 
bit. For me the documentation is an aggregation about loose components. 
If I am a new user it is hard to catch the whole picture.

I would like to lead the user through the documentation by telling him e.g.:
- what is lenya
- how lenya works
- when to use lenya (with which task can lenya help me)
- how to get started
- how to create an own
--pub /
--doc-typ/
--workflow

Each section would have an *abstract* [what the user *will* learn], a 
main area [here the user learns by explanation of concepts and examples] 
and a summary [which concepts he should now be able to master, where to 
go next and why to go there]

I would like to see the documentation as the *ultimate* ressource of 
lenya-specific knowledge! I would like to say someday to an user: 
*Everything* what you are looking for you *WILL* find in the documentation!

I *DO NOT* want to take one page and put it to another location! I 
*want* a *guided* documentation.

"[...] enough documentation content to justfiy it i am -1 for 
restucturing. "

That is the whole point there is not enough and the old ones explains 
just components! It is like you want to explain me a car. You start to 
explain what is a motor, wheel, ...
...but what I want to know is what is a car, how can I use the car, what 
can help me driving my car...

Do you see my point? To make a long story short I am missing the thread 
(de "roter faden").

WDYT?

thorsten

-- 
Thorsten Scherler

Departamento de Desarrollo de Proyectos
Sociedad Andaluza para el Desarrollo de la Sociedad de la Información S.A.U.
Avda. de la Arboleda s/n
41940 - Tomares,  (Sevilla)
Tlfn: (+34) 955 062 627
e-mail: thorsten.scherler.ext@juntadeandalucia.es

Este correo electrónico y, en su caso, cualquier fichero anexo al mismo,
contiene información de carácter confidencial exclusivamente dirigida a su
destinatario o destinatarios. Queda prohibida su divulgación, copia o
distribución a terceros sin la previa autorización escrita de "Sociedad
Andaluza para el Desarrollo de la Sociedad de la Información, S.A.U.". Si no
es Ud. el destinatario del mensaje le ruego lo destruya sin hacer copia
digital o física, comunicando a Sociedad Andaluza para el Desarrollo de la
Sociedad de la Información S.A.U. vía e-mail o fax la recepción del presente
mensaje. Toda declaración de voluntad contenida deberá ser tenida por no
producida. Gracias.
____________________________________________________________________________
___________________

The information in this e-mail and in any attachments is confidential and
solely for the attention and use of the named addressee(s). You are hereby
notified that any dissemination, distribution or copy of this communication
is prohibited without the prior written consent of "Sociedad Andaluza para
el Desarrollo de la Sociedad de la Información, S.A.U.". If you are not the
formal receiver of this message please destroy it without making any digital
or physical copy and inform "Sociedad Andaluza para el Desarrollo de la
Sociedad de la Información S.A.U." , by e-mail or fax, of the reception of
the present message. Any whatsoever involuntary declaration contained
herewith must be taken as having no legal effect. Thank you.



---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org


Re: [Documentation] Refactoring docu

Posted by "Gregor J. Rothfuss" <gr...@apache.org>.
Thorsten Scherler wrote:

> For us that would mean divide the existing docs into following 
> categories (e.g.):
> *user guide*
> -Tutorials and How-Tos-wiki ...
> --FAQ
> --...
> -Editors
> ---HTML Form Editor
> ---HTML One Form- developer guide
> ...
> 
> *developer guide*
> -Architecture
> ...
> -API
> ...

this is an age old discussion :) we have re arranged the structure a 
couple times by now. unless there is enough documentation content to 
justfiy it i am -1 for restucturing.

-- 
Gregor J. Rothfuss
Wyona Inc.  -   Open Source Content Management   -   Apache Lenya
http://wyona.com                   http://cocoon.apache.org/lenya
gregor.rothfuss@wyona.com                       gregor@apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org