You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Ted Husted <hu...@apache.org> on 2004/12/20 16:23:54 UTC
Documentation Roadmap
Documentation for 1.3++ has come up in a couple of threads, and I wanted to jot something down before I forgot.
In the 1.3.x series, we are moving taglibs to a separate project, which gives us a chance to revisit the documentation.
For core, I would like to use the DTD as the basis for the documentation. (We even have an enhancement ticket to do so.) Sections 0 and 1 of the User Guide could stay as is, but after that, we could march through each element the DTD, combining the existing DTD material with stuff we have scattered throughout sections 2 - 4. (In other words, expand 5 to incorporate 2-4.)
0 - Preface
1 - Introduction
2 - struts-config.xml
3 - Form Beans
4 - Exceptions
5- Forwards
6 - Action Mappings
7 - Action
8 - Controller
9 - Messager Resources
10 - Plug Ins
11 - web.xml
12 - Getting Started
Then do the same for the Validator and Tiles DTDs.
>>From an all-important maintenance perspective, we would update, add, or delete User Guide sections as corresponding changes are made to the DTD elements.
When available, we could also link to corresponding Developer Guides (JavaDoc package descrptions). Right now, we have these for the Validator and Util package, but we should also have Developer Guides for Action, Config, and Upload, to help pull people into our very excellent JavaDocs.
Again, from a maintenance perspective, we would update, add, or delete Developers Guides as changes are made to the corresponding Java packages.
* User Guide == DTD
* Developers Guide == Java Packages
For taglibs, what we have works for me. We could just move the Bean, HTML, Logic, Nested, and Tiles Developer Guides and API references into the new subproject, and add an overview.
-Ted.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation Roadmap
Posted by Eddie Bush <ea...@gmail.com>.
Seems an odd order for me. I would think a person would want to see
it from general to specific. To acheive this, it seems like we'd
proceed more like:
0 - Preface
1 - Introduction
2 - web.xml - Some blurbage about the role of this file in Struts operations.
2.1 - Relevant elements of config from here
.
.
.
2.x - ... through here
3 - struts-config.xml - Some blurbage about the role of this file in
Struts operations.
3.1 - Elements of config from here
.
.
.
3.x - ... through here.
4 - Getting Started
*shrug* The important thing is that there is documentation that
accurately reflects the state of the project (like you said). The
form, for those really willing to look, is less important.
On Mon, 20 Dec 2004 10:23:54 -0500, Ted Husted <hu...@apache.org> wrote:
> Documentation for 1.3++ has come up in a couple of threads, and I wanted to jot something down before I forgot.
>
> In the 1.3.x series, we are moving taglibs to a separate project, which gives us a chance to revisit the documentation.
>
> For core, I would like to use the DTD as the basis for the documentation. (We even have an enhancement ticket to do so.) Sections 0 and 1 of the User Guide could stay as is, but after that, we could march through each element the DTD, combining the existing DTD material with stuff we have scattered throughout sections 2 - 4. (In other words, expand 5 to incorporate 2-4.)
>
> 0 - Preface
> 1 - Introduction
> 2 - struts-config.xml
> 3 - Form Beans
> 4 - Exceptions
> 5- Forwards
> 6 - Action Mappings
> 7 - Action
> 8 - Controller
> 9 - Messager Resources
> 10 - Plug Ins
> 11 - web.xml
> 12 - Getting Started
>
> Then do the same for the Validator and Tiles DTDs.
>
> >From an all-important maintenance perspective, we would update, add, or delete User Guide sections as corresponding changes are made to the DTD elements.
>
> When available, we could also link to corresponding Developer Guides (JavaDoc package descrptions). Right now, we have these for the Validator and Util package, but we should also have Developer Guides for Action, Config, and Upload, to help pull people into our very excellent JavaDocs.
>
> Again, from a maintenance perspective, we would update, add, or delete Developers Guides as changes are made to the corresponding Java packages.
>
> * User Guide == DTD
> * Developers Guide == Java Packages
>
> For taglibs, what we have works for me. We could just move the Bean, HTML, Logic, Nested, and Tiles Developer Guides and API references into the new subproject, and add an overview.
>
> -Ted.
--
Eddie Bush
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation Roadmap
Posted by Ted Husted <hu...@apache.org>.
We can still provide FAQs and HOW-TOs, as we do now.
* http://struts.apache.org/faqs/index.html
But as to the foundation documents for each subproject, we need to recognize that our resources are extremely limited.
The User Guide as it stands is very hard to keep current, and Committers are always wondering where to document some new task.
-Ted.
On Tue, 21 Dec 2004 08:32:21 -0500, Phil Steitz wrote:
> The one thing that might be lost in this approach is the task focus
> -- i.e., the "Building..." view. An alternative might be to add
> something like what maven has here
> <http://maven.apache.org/reference/project-descriptor.html> for the
> struts-config DTD and leave the User Guide strucutured the way it
> is, but including links into the relevant sections of the "DTD
> reference". That way users would have both a quick tech reference
> and a guide useful for introducing / understanding app development
> with struts.
>
> Just my 2c.
>
> Phil
>
>
> Ted Husted wrote:
>> Documentation for 1.3++ has come up in a couple of threads, and I
>> wanted to jot something down before I forgot.
>>
>> In the 1.3.x series, we are moving taglibs to a separate project,
>> which gives us a chance to revisit the documentation.
>>
>> For core, I would like to use the DTD as the basis for the
>> documentation. (We even have an enhancement ticket to do so.)
>> Sections 0 and 1 of the User Guide could stay as is, but after
>> that, we could march through each element the DTD, combining the
>> existing DTD material with stuff we have scattered throughout
>> sections 2 - 4. (In other words, expand 5 to incorporate 2-4.)
>>
>> 0 - Preface
>> 1 - Introduction
>> 2 - struts-config.xml
>> 3 - Form Beans
>> 4 - Exceptions
>> 5- Forwards
>> 6 - Action Mappings
>> 7 - Action
>> 8 - Controller
>> 9 - Messager Resources
>> 10 - Plug Ins
>> 11 - web.xml
>> 12 - Getting Started
>>
>> Then do the same for the Validator and Tiles DTDs.
>>
>>> From an all-important maintenance perspective, we would update,
>>> add, or delete User Guide sections as corresponding changes are
>>> made to the DTD elements.
>>>
>> When available, we could also link to corresponding Developer
>> Guides (JavaDoc package descrptions). Right now, we have these
>> for the Validator and Util package, but we should also have
>> Developer Guides for Action, Config, and Upload, to help pull
>> people into our very excellent JavaDocs.
>>
>> Again, from a maintenance perspective, we would update, add, or
>> delete Developers Guides as changes are made to the corresponding
>> Java packages.
>>
>> * User Guide == DTD
>> * Developers Guide == Java Packages
>>
>>
>> For taglibs, what we have works for me. We could just move the
>> Bean, HTML, Logic, Nested, and Tiles Developer Guides and API
>> references into the new subproject, and add an overview.
>>
>> -Ted.
>>
>>
>> ------------------------------------------------------------------
>> --- To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org For
>> additional commands, e-mail: dev-help@struts.apache.org
>>
>
> --------------------------------------------------------------------
> - To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org For
> additional commands, e-mail: dev-help@struts.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation Roadmap
Posted by Phil Steitz <ph...@steitz.com>.
The one thing that might be lost in this approach is the task focus --
i.e., the "Building..." view. An alternative might be to add something
like what maven has here
<http://maven.apache.org/reference/project-descriptor.html> for the
struts-config DTD and leave the User Guide strucutured the way it is,
but including links into the relevant sections of the "DTD reference".
That way users would have both a quick tech reference and a guide useful
for introducing / understanding app development with struts.
Just my 2c.
Phil
Ted Husted wrote:
> Documentation for 1.3++ has come up in a couple of threads, and I wanted to jot something down before I forgot.
>
> In the 1.3.x series, we are moving taglibs to a separate project, which gives us a chance to revisit the documentation.
>
> For core, I would like to use the DTD as the basis for the documentation. (We even have an enhancement ticket to do so.) Sections 0 and 1 of the User Guide could stay as is, but after that, we could march through each element the DTD, combining the existing DTD material with stuff we have scattered throughout sections 2 - 4. (In other words, expand 5 to incorporate 2-4.)
>
> 0 - Preface
> 1 - Introduction
> 2 - struts-config.xml
> 3 - Form Beans
> 4 - Exceptions
> 5- Forwards
> 6 - Action Mappings
> 7 - Action
> 8 - Controller
> 9 - Messager Resources
> 10 - Plug Ins
> 11 - web.xml
> 12 - Getting Started
>
> Then do the same for the Validator and Tiles DTDs.
>
>>>From an all-important maintenance perspective, we would update, add, or delete User Guide sections as corresponding changes are made to the DTD elements.
>
> When available, we could also link to corresponding Developer Guides (JavaDoc package descrptions). Right now, we have these for the Validator and Util package, but we should also have Developer Guides for Action, Config, and Upload, to help pull people into our very excellent JavaDocs.
>
> Again, from a maintenance perspective, we would update, add, or delete Developers Guides as changes are made to the corresponding Java packages.
>
> * User Guide == DTD
> * Developers Guide == Java Packages
>
>
> For taglibs, what we have works for me. We could just move the Bean, HTML, Logic, Nested, and Tiles Developer Guides and API references into the new subproject, and add an overview.
>
> -Ted.
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation Roadmap
Posted by Dakota Jack <da...@gmail.com>.
You know what really is helpful for newbies, in my opinion? A really,
really good overview that gives them a sense of what the big picture
is. This layout helps that, in my opinion. I realize, however, that
different people think differently about these things.
Jack
------------------------------
"You can lead a horse to water but you cannot make it float on its back."
~Dakota Jack~
"You can't wake a person who is pretending to be asleep."
~Native Proverb~
"Each man is good in His sight. It is not necessary for eagles to be crows."
~Hunkesni (Sitting Bull), Hunkpapa Sioux~
-----------------------------------------------
"This message may contain confidential and/or privileged information.
If you are not the addressee or authorized to receive this for the
addressee, you must not use, copy, disclose, or take any action based
on this message or any information herein. If you have received this
message in error, please advise the sender immediately by reply e-mail
and delete this message. Thank you for your cooperation."
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation Roadmap
Posted by Hubert Rabago <hr...@gmail.com>.
Actually, I agree with Eddie that this may not be so intuitive for
newbies. However, this would be great for those with a basic
understanding of Struts but looking for clarification on certain
things. For instance, when I respond to user questions with something
I say is generally recommended, I like to specify a link to the manual
where the recommendation is made. The current version doesn't make
finding stuff very easy, but this layout could.
Like Ted said, for newbies who are really just starting out, the FAQs
and HOW-TOs might be a better starting point.
Hubert
On Wed, 22 Dec 2004 07:53:57 -0800, Dakota Jack <da...@gmail.com> wrote:
> On Mon, 20 Dec 2004 10:23:54 -0500, Ted Husted <hu...@apache.org> wrote:
>
> > 0 - Preface
> > 1 - Introduction
> > 2 - struts-config.xml
> > 3 - Form Beans
> > 4 - Exceptions
> > 5- Forwards
> > 6 - Action Mappings
> > 7 - Action
> > 8 - Controller
> > 9 - Messager Resources
> > 10 - Plug Ins
> > 11 - web.xml
> > 12 - Getting Started
> >
> > Then do the same for the Validator and Tiles DTDs.
> >
>
> My $.02 is that this order actually will be easier for newbies. +1
>
> Jack
>
> --
> "You can lead a horse to water but you cannot make it float on its back."
>
> ~Dakota Jack~
>
> "You can't wake a person who is pretending to be asleep."
>
> ~Native Proverb~
>
> "Each man is good in His sight. It is not necessary for eagles to be crows."
>
> ~Hunkesni (Sitting Bull), Hunkpapa Sioux~
>
> -----------------------------------------------
>
> "This message may contain confidential and/or privileged information.
> If you are not the addressee or authorized to receive this for the
> addressee, you must not use, copy, disclose, or take any action based
> on this message or any information herein. If you have received this
> message in error, please advise the sender immediately by reply e-mail
> and delete this message. Thank you for your cooperation."
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation Roadmap
Posted by Dakota Jack <da...@gmail.com>.
On Mon, 20 Dec 2004 10:23:54 -0500, Ted Husted <hu...@apache.org> wrote:
> 0 - Preface
> 1 - Introduction
> 2 - struts-config.xml
> 3 - Form Beans
> 4 - Exceptions
> 5- Forwards
> 6 - Action Mappings
> 7 - Action
> 8 - Controller
> 9 - Messager Resources
> 10 - Plug Ins
> 11 - web.xml
> 12 - Getting Started
>
> Then do the same for the Validator and Tiles DTDs.
>
My $.02 is that this order actually will be easier for newbies. +1
Jack
--
"You can lead a horse to water but you cannot make it float on its back."
~Dakota Jack~
"You can't wake a person who is pretending to be asleep."
~Native Proverb~
"Each man is good in His sight. It is not necessary for eagles to be crows."
~Hunkesni (Sitting Bull), Hunkpapa Sioux~
-----------------------------------------------
"This message may contain confidential and/or privileged information.
If you are not the addressee or authorized to receive this for the
addressee, you must not use, copy, disclose, or take any action based
on this message or any information herein. If you have received this
message in error, please advise the sender immediately by reply e-mail
and delete this message. Thank you for your cooperation."
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org