struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ted Husted" <hus...@apache.org>
Subject Re: Users guide
Date Mon, 12 Feb 2007 13:40:28 GMT
After six years of maintaining the Struts 1 User Guide, for what its
worth, here's some personal feedback.

* Separating the content into model, view, and controller sections is
often problematic since most workflows cross that boundary. It's hard
to discuss a routine task beginning to end.

* It's often hard to decide where to place a new feature. Toward, the
end, things just started to get tacked on to the end. We see that
happending again with sections about "plugins" and "portlets".

Another key problem, that snippets would help cure, is keeping
embedded examples in sync with changes to the code base.

It's also not clear whether the intention is to create new content or
link to the old. I can tell you that significant refactorings in
Confluence are a lot of work. (And that's coming from a guy who
obviously doesn't mind hard work.) I really enjoy the quick, roundtrip
editing a wiki like Confluence provides, but large scale structural
changes are very, very painful.

My suggestion would be to look at the existing content as an
encyclopedia (or wikipedia), augmented by tutorials and FAQs.
Personally, I'd suggest putting the effort into expanding the
bootstrap tutorial, merging it with the CRUD tutorial, making sure all
the FAQs on the list actually end up in the FAQ, and making the rest
of the wiki the best encylopedia that it can be. There are also still
many places where we don't use snippets hard enough, and so the
content is out of date.

But, we all have to scratch our own itches, and if a book-style user
guide is your itch, more power to you :)

Just, please, please, please, keep in mind that we have to maintain
the documentation over the very long term, and we need to keep the
content normalized and update friendly.

-Ted.


On 2/11/07, Musachy Barroso <musachy@gmail.com> wrote:
> Phil and I started to work on a "User Guide" that resembles the one from S1,
> to help new users learn  S2:
>
> http://cwiki.apache.org/confluence/display/WW/User+Guide
>
> Every time you contribute to this guide, a donation will be made to the New
> Users Foundation :)
>
> musachy
>
> --
> "Hey you! Would you help me to carry the stone?" Pink Floyd

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


Mime
View raw message