Documentation complaint: Getting started is HARD!

Sorry, but.. Welcome to the club!

I thought that my problem was the cultural differences, and language barrier, that limited my ability to find the documentation to what I wanted, so long time ago I stopped looking for documentation except for the win-help, which is very good (although not perfect), and kbase.

Starting with Progress would have been a pain if not supported by experienced people. Documentation for Architect/PDF/whater the next name would be, apparently is *not necessary* as it is "Eclipse based" (as if that were a good thing..)

My conclusion was (and still is), that Progress is not for new people, is for experienced users. The only way into Progress is by the hand of a experienced developer.. no available route for a standalone new user of it.. Maybe because no big company has such a user?

Finding new developers seems to be a no-no for Progress since ever (based on others comments.. and my company experience). So if you ask me, I'm not surprised at all..

Documentation has been an issue that I've hammered on PSC for years. The 11.3 release was a huge improvement over the old stuff - but as you can see there is still much room for improvement.

And yet, I have had no trouble taking programmers with experience in higher level languages and databases and turning them into ABL programmers with dispatch.

Certainly, Thomas.  ABL is not hard to learn -- and the docs are a bit better there.  But that's a different world.  Simply getting a trial system and reading the docs is the way a lot of new programmers learn a system.  That's how I got started with Progress.  I don't think I could do that today.

If you (or someone like you) hired me, getting started would be much easier.  Put me in a room with experienced users who can guide me past the rough spots, who will direct me to what I should read and what I should ignore, and who can answer the "stupid" questions without my having to spend hours searching for them -- and I would would be up to speed fairly quickly.  

This community can stand in stead of such a room, but I don't like to ask questions here unless I cannot answer them myself.  I can sometimes spend hours/days in the attempt.

It is not my intention to disparage Progress; I would rather see it succeed beyond my wildest imaginings.  But a few things need to happen first, and this is one of them.

In the spirit of constructive criticism:

I would like to see a series of tutorials on how to build AutoEdge, or at least parts of it.  It could step a new user through the tools and the development environment, and then in a second pass and step users through a second time to demonstrate best practices.

The best documentation for beginners I have found is FreeBSD documentation.

If you follow the manual, everything is there, in a simple and concise explanation, with references to the detailed material. You don't need to read it all, just search for what you are looking for, and it's there.

Progress has lots of excellent documentation, but it lacks the "manual" that guides you through. Adding the "global" manual will solve most of the documentation problems. And I don't mean a list of the available documents, but a very concise manual (that will be a huge one) with every subject, in it's shortest expression.

I've not looked in any detail, and apologies if you've found it already, but there is a getting started area that goes with the Classroom edition. Maybe there's some stuff here? documentation.progress.com/.../index.html

I had suggested a PDF version of the old "pocket progress" that was a small binder years ago.

Thanks, James.  I did come across that, and found that it pointed to a document on PDSOE which I had missed -- but which is actually worth reading:  Progress® Developer Studio for OpenEdge® Online Help.  I think I had ignored it assuming it was going to be something akin to the help facility in PDSOE -- containing some small nuggets of wisdom, but chopped up and impossible to simply read.  I was wrong; it's an actual document, and it covers a lot of material.  I don't know how valuable it will be, but at least it is a bona fida PDSOE manual.

So, score one for Progress.  I wish I had found this first.

Thanks, Tim.  I agree with you -- I *loved* Pocket Progress.  But eventually last copy (v9?  I think) got so far out of date that it ceased to be useful.  I can find things as quickly in the PDF of the reference manual.

But that only takes you so far.  Learning ABL is not too bad; the reference manual is straightforward, and I don't mind reading material like that.  It is really the IDE stuff -- PDSOE, Kendo UIB, etc that is making me nuts.

I do wish they would check the sample code in the documentation.

For the DISPLAY statement, 4 of the samples just won't run because of errors.

I can imagine this is very discouraging for devs learning OE (seeing as this is a 101-statement)

I know it's a bit of a pain to do, but you can raise documentation bugs through Supportlink and they're pretty good at addressing them. 

One thing I would also like to add - it would be nice to have a list (one might exist but I don't have it) of what is required to develop an application using some of the newer than version 10 stuff.  For instance I have progress 11.3 of Unix and windows but can only develop in app builder or vi (progress supplied by ERP vendor).  I have been trying for a while to find out what I tools and software I need in order to start developing in Webspeed, or what is Progress Developer studio vs. Progress Studio, What is need to create a REST service or some Java connection through the existing Tomcat service I have.  I have found this quite difficult to find this information

There's the legacy OE Application Server (asbman) which would require Developer Studio to build the WAR and link the JSON input/outputs to Progress code; this would be deployed using the standard REST servlet.  But there's now the new Pacific App Server; which I haven't used since it's an extra for more or less the same functions.

This is sort of what I had figured out but I don't have developer Studio, and before going to try an purchase it I want to know what all the other pieces I am missing are, but cannot easily determine this.  also until we upgrade the ERP release  we cannot get an upgrade progress so no KUIB until a new version of Progress

Having given this a bit more thought, I'd like to make some additional suggestions about how Progress might make better inroads into the young developer community.

1)  Make it a project.  

Hire a few bright kids out of college, put them in a room for a month, and tell them to "learn our product."  Then watch over their shoulders -- put someone in the room, use video, record their actual PC sessions, or perhaps all of the above.  (I think of this is the "Jared Spool" approach.)  You will find holes and plug them quickly that way.

2)   Make it a wiki.

Have a wiki page (or set of pages) dedicated to "getting started" docs, videos, tutorials, and the like.  This should be well organized and will moderated; every link needs to be checked at least once a year.  Make sure there is an easy way to leave feedback about things that don't work or are out of date.  If the feedback is valid, publish it next to the offending materials until the issue is fixed; don't make everyone have to trip over the same problem.

3)  Make it a class.

Progress has some top people in many fields.  Perhaps it could spare one or two of them for a year to teach a few classes at some local college or university -- say, one on Database Programming with OpenEdge ABL, one on Modern User Interface Design, and one on Working to a Reference Architecture.  .Progress would make all of the necessary software available to the college at little or no cost -- much easier to do now that it has a subscription model with built-in expiration dates.  At the end of the year, Progress would organize the course materials and offer them to colleges and universities everywhere.  Partner with professors who want to teach something using Progress tools -- you supply the tools, they create the course materials for others to use.  Maybe make a deal with students in these classes to supply them with a 2-year developer kit

The more new programmers you can get using Progress, the more exposure Progress will have across the industry as they get hired.  And the greater the likelihood that a few of them will advance to decision-making positions and pick Progress tools in years to come.

4)  Make it a cookbook.  This is a repeat of my suggestion from above, included here for completeness.  Come up with an interesting project -- like AutoEdge -- but instead of creating it fully formed as if from the forehead of Zeus, build it a small step at a time.  (I have looked at AutoEdge code.  It is nearly impossible to learn anything from it unless you are already an expert.)  In addition -- and this is critical! -- as you move to more advanced topics (PDSOE, AppServer, BPM, Kendo UIB, Kendo UI, etc.), make sure that the other parts of the project do not depend on these modules.  

For instance:

-- If you need business rules, show how to do something simple in ABL, then show how to replace it with BPM.  Users that don't have BPM can skip this, and the code will still work.

-- Show them a working character interface.  Then show them how to replace it with a a working GUI interface.  Then show them different ways they can replace this -- with .Net, Kendo UIB, Kendo UI, KinVey, or what-have-you.  But if they never do this, they still have a working application.

-- Explain what options you might pick to create a new REST interface in PDSOE, and why.  Then pick one and build and example.  Maybe suggest additional work that might be done "as an exercise to the reader."   If someone doesn't have PDSOE, but they need REST for some other part of the project, explain how to read and use the provided sample code -- which they can copy and modify for their own projects.

-- Etc.

This is a lot of work -- but from my perspective, it would be a tremendous investment. A good friend told to me at the conference (I won't name names), "there is no way to learn to use these tools without sitting down in a room with someone who knows how to use them."   That's very nearly true -- and bodes poorly for the future.  if I can sit down with a new language or tool and be productive quickly and easily, the odds are much higher that I will return to it.

5)  Make it community driven.  Have a place where people can say "I would love to see this," or "I had trouble with that," or even better "Here is something I wrote that you can use."

6)  Make it a mindset.  Take one or two people, and make it their job to think about the product as if they were new to it.

I am sure that there are dozens more ideas like these.  We are all (well, almost all) here because we like using Progress and want it to succeed.  So let's think positive -- suggestions, rather than complaints.  How would you bring Progress to the next generation?

[quote user="Robert Cohen"] have been trying for a while to find out what I tools and software I need in order to start developing in Webspeed, or what is Progress Developer studio vs. Progress Studio, What is need to create a REST service or some Java connection through the existing Tomcat service I have.  I have found this quite difficult to find this information [/quote]

Those are great questions, Robert.  I'm not sure I have all the answers, but here are a few notes that might help.  Possibly it's more than you want to know, in which case I apologize.  :-)

Progress does not speak REST directly; you create code that responds to specific calls (typically with Progress Developer Studio for OpenEdge), and then deploy it on an AppServer -- either Classic or Pacific.   The AppServer matches the incoming requests to the ABL methods.  If you don't have PDSOE, I will mention that you can do this the hard way:  A couple of years back I was having no luck deploying from PDSOE, so I took a working deployment and painstakingly modified it to meet my needs.  (This includes making changes to certain zipped resources within the deployment.)  Not recommended, but it was an emergency, and it worked.

WepSpeed was once a separate product, but now it is bundled into the AppServers.  If you have it, you can create WebSpeed code with "vi" or any other tool you choose.  There are various ways that the web server can call your WebSpeed code, including CGI.  (Note:  The new Pacific / OpenEdge App Server includes both WebSpeed and a working web server; no need for CGI scripts or anything like that.)

I think it would be difficult to deploy a Progress REST service to an existing Tomcat installation without an AppServer; you would have to hook in something that runs Progress -- sort of building your own AppServer.  But like many such things, it can probably be done if you are both clever and desperate enough.

As for the two Studios:  I have lost track of the older editions but Developer's Studio is the newer Eclipse-based product  I thought I would check the web site to remind me of the details -- but these are completely missing from the Progress Products web page (<www.progress.com/products>),   Appropriate to the topic at hand, no?

Not that you asked, but:

There are also DIY alternatives, if you are limited in the resources you can purchase or deploy onto your system.  For instance, Progress is powerful enough to listen to port 80 and to respond to web requests directly, but you lose all the advantages of working in a highly tested and stable multi-threaded web-server as your front end.  you can create web pages or even handle REST requests.  But your ABL program is single-threaded, and if it dies for any reason you are responsible for making sure it respawns.

There is also sample code for interfacing OpenEdge to node.js.  (See the PUG Challenge America conference site -- http://pugchallenge.org/ and search for node.js on the download sites for 2013 and 2014,)  I played with the node4jprogress code some years ago as a way to have some live web-based dashboards at a site that had only a Progress Runtime License.  Among other things, node.js handled request queueing; it was a cheap and effective alternative to an AppServer in this simple and low-activity environment.  (NB:  If you do this, you need to consider how these processes affect the user count in your license.  For the best deal, be sure that you understand your license and think the issue through; then call your sales rep.)

I hope that something here is helpful to you,

-- Phil

Phil,  I enjoyed reading your list on how to evangelize the Progress development tools to the younger generation.  Another point quickly came to mind. 

(7) Make Progress use OE internally.  Use it for all internal systems, even mission-critical ones.

If OE is the right platform to build mission-critical business systems, then Progress needs to lead by example, and show us how its done.   Progress should be using it to meet all its own internal business needs.  A company can only build great software development tools when it is dogfooding. Based on my observations, it seems very doubtful that Progress uses OE to build all its own internal systems (ERP, CRM, Customer Support interface, etc).

Also I think Progress has to commit to hearing and fixing developer stories; this can be expedited if Progress would start by using the tools themselves.

Folks, PSC /does/ use OpenEdge for a variety of its internal systems but not all.

We did more in the early days, but building your own ERP system is a lot of work and requires a lot of people. Eventually PSC became a QAD customer and replaced some internal systems with MFG/PRO. Don’t know what they use now.

Writing your own complete email system is also a lot of work. Not at all practical when there are commercial and open source systems that do this extremely well. Even running your own email system is a lot of work. That’s why a lot of companies use gmail.

At one time, the Sam Adams brewery used Progress and wrote their own applications for accounting and beer tasing record keeping and such. Eventually they figured out that they should spend their time making beer, not software. The whole reason why packaged software is so popular is that it is too inefficient to make everything yourself.

Do you do all your own car repairs?

Progress at it's core (at least OpenEdge) is OLTP.  Online Transaction Processing isn't the most exciting thing in the world and I guess in the end is a bit abstract for new programmers who are excited about the look and feel of their programs - Colors!  Beeps!  Movement!

I'll admit to wanting to be a developer for some NASA project when in college - computers in spaaaaaace!  But reality for me is "record shuffling" pays the bills and it has done well for me so far.

So until you find a way to get a programmer excited about the details in an accounting system, or a loan system, or a service system, or a law system, or an inventory system, etc. there really isn't going to be to much excitement for Progress.  There will not be a "look at this cool video system I made, or cool music system I made, or Facebook/MySpace/Friendster system I made" blah blah blah.  The language isn't made for that stuff.  

When it comes down to interests there are two - what is interesting to me (the programmer) and what is interesting to the world (the app.)

Ya need to get new programmers (usually young people) to look past their interests and see what the rest of the world wants.  The age old way of doing this is the ole "if you scratch my back, I'll scratch your back."

They need to understand that Progress is a back scratcher that they can use to achieve the above.

Now there is living on anothers plantation issue at work too.  Most of the good stuff made out there is in C or C++ (take a look around your Linux system) or PHP for the web goodies or whatever is going to be free for mobile development (believe me, it's coming.)  The point I am making is that those languages are free except for the books and even those are free if you want to spend time reading PDFs and watch some videos.  They are free to develop in and free to redistribute your app in.

Progress obviously doesn't even want the development to be free so it is chained to people who want to pay a couple thousand for the tools or people who want to work on OLTP systems (they will already have some education in development.)

So, yes, getting started is hard and we recognize the need for “How do I …” content and content that isn’t just reference material.

You will be happy to hear that we are working to address it. Part of our new SAFe development process is the heightened awareness of the importance of doc and other formats of learning content in the product delivery process, and this has led to us forming a Content Strategy group with representation from Dev, PM, Services, TS and other groups.

One of the challenges of "put a bunch of interns in a room and slide pizza under the door until they're done" is that good content requires a certain depth of knowledge about the product/feature you want to write about.

We'd love to hear from you about:

- what kinds of information you'd like to see

- how and where do you currently look for it? Pure google? Progress communities? Stackoverflow? Documentation.progress.com?

- how and where would you like to?

- along with that, what's the context you're looking for? This is a little nebulous but we recognize that you don't always get the answer directly on the first look. Sometimes looking for a keyword leads to more questions about usage.

- what media/format works best for you (doc/pdf or wiki or video or regular webinars or web-based or online training courses)?

- where do you consume help/doc/etc? in dev tools or always in the browser?

- would you want to contribute to the content (assuming some form of mild moderation to prevent trolls)?

Kris

When I started reading this thread,after 6 or 7 rows away, I tought (is this guy reading my mind?)  That's exactly how I felt 24 months ago, when starting aproaching Appserver.  Now I use it profusely from 12 months on...  So it took me 12 months, to keep the internall flow of client/server development with the figuring out of appserver (meaning it was more important to keep up, than modernising).  I'm here with me and my self.  I'd kill for having Dr. Mercer-Hush somewhere near here to ask "simple, stupid questions", that we all face when starting something.

(I remember back 1996 when all began for me, I spent 1 day searching answer to the simply statement "indicate port number" when starting database,  after that, a call to Sales rep. proposed "2500", no justification ... nothing more...)

Today my database runs on port 2500, 20 years later, and third company I converted to progress.

I also passed by Autoedge docs, just to crash at same wall of "components not installed".

I think one "must for recruiting new souls", would be simply, straigth forward recipes.

a list step by step of simple actions, and each step has a counter part to some extened doc for each kind of project, approach, ade.  it came to my mind that I found business entities by a casual commentary in phone call to representative of progress here in Mexico I called in desperation as I wasn't able to understand some basic principles...

- why don't you use the business entity wizard?

- wait, what?

.Yes, it's under File, New, ... way below, there... business entity wizard....    (remember that 11.2 or 11.3 had the wizard at the end of menu?  (or is dinamically arranged by use frecuency?).

Any way the feelling you talk about, is the same felling every of us new to some tools on this wonderfull world of progress, got.

I'm sure there are plenty of other, better suggestions, [mention:93b1509fd7b94ab6a4994e7a4f76d331:e9ed411860ed4f2ba0265705b8793d05] , but the one thing that really bugs me in terms of getting started is the need for a new developer to have to create a database. Yes, there's the sports2000 database, but they still have to load a proenv and do a prodb/procopy or whatever. And sports2000 does not adhere to best practise in terms of its structure as well.

So, please could the install of the Classroom edition at least, come with a sports2000 database that is correctly structured (Type II storage, split into Data/Index areas, not by business function, with nothing in the schema area - all tables need an index), and then a script that can be run by double clicking on an icon that will set up a database in $DLC, along with a start/stop server script, and/or auto-configuring of settings in PDSOE.

A developer shouldn't have to worry about the database structure, so why should he/she when getting started?

Wasn't that one of the thing Tom's team aimed for in CCS... and, thought you were part of it ;)

[quote user="Mike Fechner"]

Why is Progress hard? Because it's pay-walled, It's not a native lightweight HTML environment.  No one sets out now to build a new App that requires licensing if they've a choice.  When people know something really well; they'll stick with it, but new people won't learn it, if they quite literally have to buy into it.  Open Source is now feature complete when compared to the licence based RDBMS products from any major vendor.  

As a Progress programmer and DBA the read consistency implementation with SHARE-LOCK/NO-LOCK/EXCLUSIVE-LOCK is a mess compared to SQL based it's point-in-time queries using "UNDO" / "ROLLBACK".  In Progress you have to plan when to look at the data to see it in a read consistence state or just lock the table PRESELECT SHARE-LOCK, great fun for an OLTP environment.  The RDBMS engine in Progress is showing it's age and needs some love; I don't need a sexy UI if the data is difficult to manipulate.  Triggers are broken, client must have copies of the code??? Can't believe it is still an issue with the ABL.

Yeah. Docker containers and Ansible scripts for all supported platforms...

Lots of use cases like that once you start having containers as one of the core features of OpenEdge environments ;-)