Hi Mateusz, On Thu, Feb 27, 2014 at 10:35 AM, Mateusz Zakarczemny < mateusz.zakarcze...@up2data.pl> wrote:
> Docs from 1 and 2 branch are mixed together. As far as I can see they are separate. The tutorials are clearly under different subsections, and the Nutch 2.x docs have their own section as well. > I understand that detailed documentation easily became outdated. But > providing information about the existence of the feature is very basic task > of documentation. It should be always up to date. > What exactly are you referring to here? I am slightly puzzled as to why not one other user has requested documentation on individual issues. IMHO, if people wish to use and develop Nutch, they should at minimum subscribe to user@ and dev@... the latter contains EVERY issue which is discussed and feature enhancement. The same is done for other projects. > A changeling is not features documentation. No but the point of the changelog is to refer people to what is included. We also now provide a link to the Jira release profile. It is up to users/developers to read up if they wish to learn more about individual issues. An example of such a link can be found in the 2.x CHANGES.txt Release Report - http://s.apache.org/PGa > If new user looks at Nuch he will not check the changelog but > documentation. Is this your opinion or are you commenting from a wider audiences perspective? > I think the new user should be provided with clear information about which > branch to choose. I agree with this. This is why the lists exist. You can ask questions. You can also read some archives. It takes a minimal well spent investment of time to dig up what other have asked many many times. Don't get me wrong, I am all for informing people about the software... however I am not in the immediate position to write a decent quality book on Nutch which would do the community and software justice. If you are then please do. > What is more, the doc should be divided in branch 1 and 2. Please see the table of contents on the wiki. Please also see my comments above. > Pages could link together, but there should be a clean branch tree in the > docs. As like in source code. You do not mix packages from two branches but > you keep them in separated repos. > ditto > I don't think that for bugs documentation is essential. Only for new > features or refactoring. It doesn't have to be big document. It just has to > exist. But what happens if fixing a bug changes functionality? Then what? > Nowadays there are some plugins which are not mentioned in plugin central. > It is very confusing. > Yes I agree with this. it is not entirely up-to-date. This is something we should most likely address. > I know that sometimes developers don't have time to create documentation. > But in such case they should create a new task for such doc. Otherwise > nobody knows that doc is missing and cannot help. > Not true. All you need to do is request Karma for the project wiki and you can contribute to whatever you feel is missing. I don't take this argument sorry. > I am not saying that confluence is best for this project. But in my > opinion Nutch docs should be moved to some community/social solutions. It > would be great if it enables comments and pull requests (like on github) to > improve it. > AFAICT the wiki we currently have IS community oriented. Anyone over the years that has wished to add/edit has been granted Karma to do so. Are you really saying that enabling pull request via Github is a better way than simply granting someone Karma to edit a page as they wish? > Maybe MD files would be better? Documentation could be stored with source > code. Eg. Doc folder in each plugin. It would be fixed to source code > structure. This approach has many advantages. When I contribute some doc on > github I don't have to apply anywhere or ask anybody. I just create pull > request to documentation. Project leader sees it and next could review and > apply it. Whole process take 3-4 mouse clicks. One drawback is moving to > such solution would be quite complex and time consuming. > Yes it certainly would be. > > Over last 10 years Nuch documentation grew incrementally. I think It is > time to refactor it to more modular and structured way (like source code). > I don't want to rewrite it but just create better structure. > Honestly I haven't seen anything from your commentary which would suggest benefits for Nutch as a whole... I am trying NOT to be pessimistic, but I am just struggling to see your point here. If the wiki is outdated... then we should update it. Not change to another solution just so we can receive pull requests for documentation. There is an argument to make it as easy as possible to contribute documentation to Nutch. However as far as I can see, there are not crowds of people rushing to contribute. Please don't take these comments negatively. I am behind any motion to make documentation better. I just don't see eye-to-eye with some of your points. > > > PS > My Jira username is Matzz > I've granted you Karma for the Nutch wiki. Please contribute what knowledge you have of the project. Thank you so much.
