Suggestions for documentation

I have some suggestions for documentation. 

1. Make the wiki a true wiki and let users create and edit the content.  There are enough dedicated .netTiers users that will police the documentation.  In fact, I'm sure you will find that when you go into the wiki to add some docuementation on a new feature you will find that a user has already added it.
   
2. Relevant version numbers should accompany all docuementation sections.  Some of us are still using older versions for some of our products and its very aggravating to get 90% thru a procedure just to find that a described method is not available in my version.  One would then assume that the docs refelected the most recent version, but that is not always the case either.
   
3. Freeze the development long enough to get some thorough documentation.  Add some features, freeze, and update the documentation.  Repeat.  The templates are growing too fast to keep up with.  Soon new users will be so confused by seeing the massive amount of code that they will not be able to figure out how to use it.  Without good docs, your product will stop becoming productive to the user and they will go elsewhere.  IMHO its better to have a happy user base then to add more features to a great product such as .netTiers.

Looking at the links in the pages, it appears that despite the URL, this is not actually a wiki, just a collection of static pages. If our friends at codesmith don't want to put up a real wiki, could someone else? I'm just about ready to do it myself just so I have all of the docs in one place.

One way of improving the docs would be to suggest that all new functionality ([ENH]) be accompanied by documentation. While anyone else can reverse engineer the code for docs, it is much easier for the original author in small chunks. Any format would be fine, examples or not, as long as it was easy to find. I'm just learning NT and find that the information I need is completely scattered around the existing forums.

This state of affairs is curious. Big system, active development, many users, no docs. Is someone planning on making some money in the CSLA way: publish the docs as a book? If so, please just give a hint when it might be available. To the business types: It'll be tough to penetrate the market without making the system easier to evaluate. This much learning curve is too expensive.

-Jim

We understand about the lack of documentation, but as you mentioned, big system, lots of users, etc. it's incredibly difficult to manage this with our outstanding, yet limited with resources team.  We had a wiki up and all it received was spam.  It's been on my list to move it again to another wiki, hence the wiki.nettiers.com subdomain.  It's just been a matter of time.  We're all for help! So if anyone would like to take charge of this, we'll help get the content on there, I just would like for a few community members to manage this.  CodeSmith might help sponsor .netTiers by giving me some resources to work on it, but I DO have a full-time job with CodeSmith.  So just like anyone else, my resources are limited as well.  We may also consider putting bounties up for documentation, which might help as well.

jletts:

This state of affairs is curious. Big system, active development, many users, no docs. Is someone planning on making some money in the CSLA way: publish the docs as a book? If so, please just give a hint when it might be available. To the business types: It'll be tough to penetrate the market without making the system easier to evaluate. This much learning curve is too expensive.

I would be willing to help police the wiki though I might not be able to add much.  I would be referencing it quite a bit as I do the current documentation.

Don't you think a development freeze at the next stable realease might give all you brilliant minds enought time to put together a good set of docs?  At this point the development is far outpacing the ability to make a decent set of docs.  Also every time I sort of get the hang of the templates they change.

I also agree with Jims suggestion to insist that no changes be implemented until the author also updates the docs.  That begs an interesting question regarding the wiki.  If a new version is being developed, where would the docs for that be built during the development?  Obviously the public wiki would only contain docs that pertain to to the current stable release and older versions.  I suppose the new docs could be stored offline and incorporated into the public wiki once the new version is released.

Another option is a set of docs similar to MySQL docs.  There is a complete HTML set of docs for each version but they allow for user comments to be added.