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