> Ok, so it's clear that some of us care.
I don't think anyone is accusing people of not caring, but IMHO it is a very valid complaint about *project* priorities, and that for me at least, it is the single biggest downside to TG at the moment. > We're not saying that users "have to" help with documentation, but we > are asking for help from users. > > Projects that have great docs have a team of great people who help > write documentation. This is certainly true. It's also true that expecting new users to work on docs is frankly ridiculous. A new user is still trying to figure out if they even want to stick with the platform. And the quality of docs is probably one of the biggest determiners. > Others are more interested in working software than documentation, and > frankly I want them to stay involved and keep contributing good code. > Creating too many restrictions will push them away. Well, this is where we disagree. I agree with Steve that without a clear code and doc submission policy, the current mess will not get better. I don't see signs of it doing so, only of getting worse. Most talk on the dev list is about *new* features. IMHO, forcing people to write at least a decent starting docin order to submit code will not push away developers. Everybody wants to write code more than docs, so they will do it if they need to. As I said, I have seen this work very well on the Csound project. If the idea is that someone will document it later, than we will keep getting more code that is undocumented while the docs lag further and further behind the dev code base. I brought this point up several times, and it got basically no response from any of the TG core developers. So, I agree, this is a question of project management priorities. And if it's not dealt with, we *will* lose users, lots of them. And by that token, future developers too. > If you can draw diagrams, or convert files from wiki markup to REST, > you can make a meaningful contribution. So, the only reason not to > get involved is that you have other higher priority things to do. > And if that's the case, please don't vent your frustration at other > people who might also have other important things to do and spend less > time on documentation that you would like. I don't think Steve is *just* venting, and I believe his comments definitely have a place. Telling him not to say things like this simply encourages people to "silently leave". And believe me, they are doing it whether we want to admit or not! If there is no room for critique and argument over project direction, that alone would send me away and ensure I never become a contributor. Most serious developers are totally out of touch with how critical stable and thorough docs are to new programmers. *That* is why PHP and MySQL have such massive penetration. Their docs are absolutely fantastic, and to new users that is more important than anything else. TG is currently much harder for a new user to get into than django because of docs mess and a sense of too many things going on at the same time without a clear idea to the new user of which ones and docs work with which features. There is a real sense of docs getting 80% of the way and then stopping. There's a user life cycle. Expecting users to contribute at the beginning is totally unrealistic. For the first while they are learning and auditioning the project. If they get hooked, which will take a long time, *then* they will start contributing, and then maybe later developing. For an open source project to have a bright future, IMHO it's more important to make sure this initial phase goes smoothly than to focus on new features over it. If we get lots of users, they later become developers, and the new features come in time. I understand your frustration with the vent having obviously put a lot of time into docs. I think the situation is something that should be discussed more thoroughly at the project management level. And again, I can't praise enough the Karl Vogel book "Producing Open Source Software", it covers problems like this extremely well along with a host of other things. Iain --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/turbogears?hl=en -~----------~----~----~----~------~----~------~--~---
