struts-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ken McWilliams <ken.mcwilli...@gmail.com>
Subject Re: Struts2 documentation and Stack Overflow
Date Thu, 01 Sep 2016 01:26:26 GMT
The Tao of SO is changing all the time, perceptions of what was or was not
acceptable years back have changed. Documentation being so new I think it's
hard to say exactly how it will establish its self.   SO has _a_lot_ of
struts 2 questions... 10,334 at this time. If they were all distinct that
would be staggering but a lot of questions are minute variations of
each-other, if even that. Documentation could be used to fully explain
those sets and variations, so we can reference that one source. I've
stopped answering questions largely because struts2 isn't that complicated
and if one looks for all normal use cases, they've been addressed...
probably in triplicate.

What I am getting at is not reinventing the wheel. "About Struts", "About
Tags", "About Interceptors" there are things that can be said but in the
main, if it was to be all done over by several different groups... they
would probably need to speak to the same things before going someplace new.
Without some duplication, everything would be links. Which in theory makes
sense, in practice would result in unreadable garbage that wouldn't likely
be expanded upon.

I don't think it's any reflection on poor documentation by developers. The
Struts 2 documentation is very good. Sometimes the user community will do
interesting integrations, it would be trivial to plug this into
documentation but harder to get into official struts2 documentation. Which
frankly should probably be concerned with core functionality, aside from
plugins which document common integrations such as Spring. There are some
confusing areas involving some plugins that could stand for some user
supplied documentation. I think people would be more inclined to contribute
with some framework in place.

Anther way to put it, while the developer mind set is to factor out
commonality, "boiler plate is bad" It's really hard to create documents
without boiler plate. Templates and skeletons are our friend. I don't want
to move the whole site, but there are stubs that are reasonably needed.
Sound bites that have been well thought out, and silly to do over. It's not
a duplication, it's a shove another ship off the shore.

On Wed, Aug 31, 2016 at 6:04 PM, Doug Erickson <doug.erickson@part.net>
wrote:

> Stack Overflow Documentation isn't meant to duplicate existing
> documentation. It's intended to provide missing documentation and
> compensate for poor documentation.
>
> So, copying current documentation to SO is definitely not in line with
> their goals.
>
> It *could *be a place to create better documentation for Struts2, but I
> don't think so. I think Documentation's focus on examples is wrong. As an
> experienced Struts2 developer, when I need documentation, I want to look up
> something specific in a reference guide. As a beginner, examples were more
> helpful, but I would want to encounter them in a logical progression, not
> the disorganized grab bag that Documentation uses.
>
> If there's a commitment from Struts developers to improve documentation,
> they should do it on the struts site. Documentation is a place for the
> community to go to contribute their own documentation when maintainers fail
> to do a good job.
>
> On Wed, Aug 31, 2016 at 5:45 PM, Ken McWilliams <ken.mcwilliams@gmail.com>
> wrote:
>
> > StackOverflow is a pretty huge site and a lot of people seek out Struts2
> > Q&A there, it would be nice if the Struts 2 documentation was available
> via
> > the new StackOverflow documentation initiative.
> >
> > I was tempted to simply copy good chunks of the existing documentation,
> > there is certainly room for improvement but starting from scratch is
> > certainly a daunting effort.
> >
> > What is the view on copying data from struts.apache.org to SO? (I know
> > there will be others from SO who follow this list and would probably do
> > pretty reasonable and good things with a green light)
> >
> > Anyone can write a blurb, and it's looking a bit barren over there right
> > now.
> >
> >
> > --
> > Sent from my C64 using a 300 baud modem
> >
>



-- 
Sent from my C64 using a 300 baud modem

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message