In reply to Hookr (@hookr_io).

@hooker,

Not a great example. Better example:

Lots of books exist on WP coding over the years. All such books are also construed by developers as reference materials that are paid for. Whether they contribute to core work or not is rather immaterial. Some have built names for themselves in such ways and to a seasoned developer their code looks amateur. Thats not to sound pursnootity just the case as they perhaps try target an audience or target staging it up for book part deux. There are training videos monetized on.

Documenting is a sorta peeve in that documenting code is just required. Its not optional in any corporation. Heck, the only time is was sorta optional was VERY early in micro-computing when developers (I included) worked on PC Games and we'd not document engines. We did that so a publisher or another developer would need hire us if they wanted use said engine(s). But now-a-days its just required. Can you imagine trying to code even a decent Windows Form or Windows WPF or Windows Service application and have documentation thats spread all over? Microsoft would be long since dead.

I do see this ALOT in PHP Open source and I dont understand it. Perhaps it was because of no real competing other computer language base for viable Web App's short of really Java.

Now, thats different, C# and Mono are on the scene. Take a look at Mono's documentation. Then go, "Oh my... look at that". Not only will you see a framework that makes pretty much all comers look like bad swiss cheese but you will immediately notice something else. This does NOT look haphazard or cobbled. This REALLY looks like some folks who have BIG BIG BIG plans and they are providing software engineers with a very solid foundation. You would be right.

From a coders perspective its simple. If I need hunt all over for resources in documentation, if I need do web searches looking for the "right ways" and examples to do things then that is time completely wasted that I could be pumping out code. Documentation should never be a frustration area these days. 25-30 years ago, yes. Now? No. Fantastic engineer can walk into Google and say, here I am. Here's impressive code. When they ask where the documentation is if he/she says, "I dont do that" or "I let others do that" they will be shown the door.

It interrupts and erupts others work and workflows. The #2 reason WP crushed Joomla is Joomla's "We want others document our work" as we float around the globe charging money for seminars in large part do to the code third parties developed that make the platform do snazzy things.

Documenting sux. You should see how much documenting takes place with even a rather simple gaming engine. You'd go, "Oh my goodness!". Flow diagrams, state diagrams, database, objects on and on.

It is one of the "issues" that will kill open source when it comes to projects such as Mono. There is nothing and I do mean NOTHING more frustrating than hunting for documentation. Its time consuming, makes stress levels climb and takes away BIGTIME from workflows. For example, writing code, really having a productive session. Need find some info. 45 minutes later have it. That productive session may well be hindered immense like. Happens ALL the time to coders. One of the biggest beefs heard at suds night where a bunch of coders and others get together here local is that.

Want really make money Hooker? Not as a hooker? LOL. Write a book. But DONT write a book thats a "Lets learn how to "functions.php" or enqueue blah blah. Write a real quick reference book for WP. The meat and potatoes are function, hook etc. references (just like any quick reference guide) and a few small sections "Plug in basics" "shortcode basics" etc.

Then just keep updating it every year. Look at ones that Orielly has done for other languages. Do same. Contact O-Reilly firth thing Monday morning and tell them its underway. I guarantee you they will go, "Awesomesauce!" and you will make a GREAT DEAL of money.