Re: Struts2 documentation and Stack Overflow
2016-09-01 1:45 GMT+02:00 Ken McWilliams : > 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. I don't know how SO Documentations works but I would like to migrate our docs from Confluence to Markdown/pure text as a part of struts-site project - this will allow everybody to contribute via PR on GitHub. Right now collaboration of non-committers is very limited :( Regards -- Łukasz + 48 606 323 122 http://www.lenart.org.pl/ - To unsubscribe, e-mail: user-unsubscr...@struts.apache.org For additional commands, e-mail: user-h...@struts.apache.org
Re: Struts2 documentation and Stack Overflow
> From: Doug Erickson > To: Struts Users Mailing List , > Date: 01.09.2016 02:04 > Subject: Re: Struts2 documentation and Stack Overflow > > 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. > Open Source lives from contributions. And documentation is a great area where community members can contribute ;) Regards, Christoph > On Wed, Aug 31, 2016 at 5:45 PM, Ken McWilliams > 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 > > This Email was scanned by Sophos Anti Virus
Re: Struts2 documentation and Stack Overflow
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 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 > 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
Re: Struts2 documentation and Stack Overflow
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 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 >
Re: Struts2 documentation and Stack Overflow
I've not looked at the StackOverflow doc site, but I believe the documentation is auto generated by the build process, so it might be a challenge to keep it in-sync as new releases get published. On Wed, Aug 31, 2016 at 4:45 PM, Ken McWilliams 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 > -- _ Adam Brin Director of Technology, Digital Antiquity 480.965.1278
Struts2 documentation and Stack Overflow
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
