Am 05.09.13 07:51, schrieb Lukasz Lenart: > Argh..... :-) > 2013/9/4 Christian Grobmeier <[email protected]>: >> When I first looked at Struts, the website was a mess. It still is (but >> we're working on it). I was confused by countless topics. It is in my >> genes to look at the source code immediately, but the Struts sources >> were huge. Unfortunately i was not able to connect documentation to the >> source code. > Sometime ago someone did start working on the new User Guide > > http://struts.apache.org/development/2.x/docs/user-guide.html I think this is a great TOC already. If it would be finished, we would have a huge win!
>> Then I found some docs in the wiki. But the correlation of Struts >> documentation to the wiki and static webpages is black magic. Honestly, >> if I couldn't ask you (Lukasz) I would still not know how these things >> are all tied. And believe me, I am going to continue to ask you on it. > There is no correlation :-) Basically what is under /docs is exported > from Confluence /WW - so we have a dualism here ;-) > It would be cool to have everything in one place - webpage and docs > either in Confluence or as webpages (i.e. Markdown) As you know, we have hacked on Struts past weekend. We discussed docs and well, it was a pain point for a lot of them. When we elaborated further we formed some kind of a plan. First off, I fully agree - everything should be on one place. Personally I prefer to use Markdown and would like to avoid Confluence as much as possible. I don't like the idea to be tied to a commercial product with one of the most important assets we have - the docs. now, what if we would have all of our docs integrated in "mvn site"? Imagine the following scenario: - mvn site - our Struts-Create-Snippets maven plugin walks the source code, creates snippets from javadoc to /target - the Struts-Replace-Snippets maven plugin copies the markdown, then repalces the snippets previously generated - then the usual site process This would more or less allow to remove the cxf plugin dependency, opt out of Confluence and integrate site building to our usual lifecycle. We already started some effort on Saturday - well, in fact Andreas Prüller did. You can see some starting points here: https://github.com/opensourceio/struts-maven-plugins Andreas has an ICLA on file and wants to contribute to this - i put him on CC, just in case he did not subscribe already. The plan is, we collaborate further on GitHub as Andreas has write access there and the officially donate it to Struts. What do you think about this? > >> This is a huge help for others: >> http://struts.apache.org/helping.html >> >> But I believe given our huge website its hard to find. It says how I >> create a patch and how join the mailing list. But thats not enough in >> the Struts case. I would love detailled, easy to understand instructions >> how a non-committer can fix typos on our docs in less then a minute. I >> mean instructions which you don't need to search. I think we'll need to >> explain how we are building things. > Many of the informations are outdated and can overwhelm users - I > don't like to read half of page to at the end perform mvn > release:perform ;-) > > I mostly like our release guideline, yet still outdated but it tells > you step-by-step what to do. 'Why' is less important on the beginning. > > http://struts.apache.org/development/2.x/docs/building-struts-2-normal-release.html > This is fantastic. I think we should include it in an improved part of the struts main page. >> I think we should make things like >> this page: >> >> https://cwiki.apache.org/confluence/display/WW/Struts+Next >> >> more prominent. We should also explain what we would do when we start >> working on v2.5 (do we create a branch? do we just commit to the trunk? >> and so on). > There is one problem with that - why did you ask beforehand? If you > don't know something, please ask - then I can answer or update docs or > something else. The main problem here is I don't know if something is > missing, for me some informations are obvious. To be more specific and > answer your question: we will figure it out and discuss when we will > switch to Git and start working on 2.5. > > I don't like to prepare huge plans for the future - be agile, adjust, > change, go ahead ;-) hehe :-) Be assured, I am asking when I am not understanding. My point was: others, non-committers might be overwhelmed. While I agree we need to be agile, we should document our usual development workflow. I found some parts were already done, so maybe its just compiling it and put it to a better place. I am willing to go forward with this, i think its then easiert ot understand if there is something to read. >> When I go to Commons I don't have such problems. I check out a small >> component and send in a patch. If I am doing it wrong, somebody tells >> me. But in Struts land everything is so huge. >> >> For me it is all with a better documented workflow and better websites. > Good point! Is http://struts.apache.org/helping.html worth > extending/simplifying and exposing on the main page? Absolutely! I will write a new message in a minute, but I have already worked on this today. I like it much and believe the whole section could address all of my pain points I mentioned and increase the contributions. I ahve already started with giving some love to it on a branch and plan to prepare some first git documents for it too. Cheers + Thnks! > > Regards --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
