Forum > Documentation (Maintaining -)
Documentation / tutorials need improvement (was: Object Pascal decline?)
vicot:
--- Quote from: vicot on January 28, 2016, 01:00:24 am ---
--- Quote from: ArtLogi on January 28, 2016, 12:21:45 am ---The documentation. Why none (well someone did mention .. applauses) mention the documentation, if there is no documentation the next generation of programmers will not jump to the board as easily (since no easy way to learn compared to "competitors"). Yes, many of the other languages have plenty of documentation, but FreePascal itself do not have good quality non-technical documentation which I mean by that is it lacks the user level documentation and by user I do not mean a computer/software majors or old professionals with 40 years experience in programmin and last 20 years of Delphi (you don't need the documentation (only reference) with your own build ecosystem). It is also a crime for the language dialect (FP) itself to blindly say that there is plenty of external resources out there, there is not, there is plenty of documentation for other OP dialects from the past. This is something that the FPC (and in some extend Lazarus) is missing, the documentation part of the project is in sidetrack. There is no good web infrastructure to easily maintain and publish the documentation, code examples, structure snippets etc. The Wiki is cluttered and have hit and miss google UI atm. The Lazarus code filling or what ever it is called (the thing what pops out after you press dot after some objects etc) is nice, but with it you need to already know something. There is no clear path of documentation from novice to advanced user. It is unbelievable force factor, the word I mean.
--- End quote ---
You nailed it. A better documentation is badly needed.
To that I would add: better tutorials, especially video tutorials. I find it ironic that (as is the case with many other languages) you find lots of tutorials that cover the basics (syntax, control structures, etc), but not much beyond that.
Something that would be *greatly appreciated* is a proper video tutorial for Lazarus development. Again, covering not only isolated aspects of the language, but especially the program building progress. That is, how the programmer actually develops a whole program, phase by phase. You want to see how he jumps through the hoops.
Such a video tutorial would be a *huge* success, I am sure. It would pull in a large number of programmers from other languages, especially those who are sitting on the fence.
--- End quote ---
I have decided to fork the thread -- I believe that this topic deserves its own thread.
Edson:
Well, I have always been saying Lazarus/Libraries is poorly documented. But always people here, send me to read Delphi docs %).
Leledumbo:
--- Quote from: Edson on January 28, 2016, 04:08:07 am ---Well, I have always been saying Lazarus/Libraries is poorly documented. But always people here, send me to read Delphi docs %).
--- End quote ---
Not always, I also ask people to be the documenter as well ;)
marcov:
I'll reiterate some of the core points of my earlier reply
* specially a tutorial documentation is missing from FPC, and on the Lazarus side something that explains LCL architecture and principles. A good tutorial documenthas a narrative and head and tail
* I consider the wiki as the container for everything that doesn't fit the documentation scheme, not as documentation itself. Trying to learn from organically grown wikis feels like chasing your own tail
* For existing documentation, patches are still accepted.
* Videos are mainly useful to get the hang of the IDE. (because that is very visual, where to click etc). But as a general tutorial principle I don't like it, it is always either too slow (detailed) or skips too many steps depending on your current level in the subject.
"Poorly documented" is very subjective and meaningless without context. Except for people that just want to be negative.
To get something done, more manpower is needed. Manpower that actually write something, not just blame the tools and write endless threads.
jack616:
Load Delphi(3?)
Put the cursor on a keyword
press F1
Analyse the page you get carefully.
That is the documentation needed.
Navigation
[0] Message Index
[#] Next page