Recent

Author Topic: Documentation / tutorials need improvement (was: Object Pascal decline?)  (Read 13596 times)

vicot

  • Full Member
  • ***
  • Posts: 114
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.

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.


I have decided to fork the thread -- I believe that this topic deserves its own thread.
« Last Edit: January 28, 2016, 06:43:57 pm by vicot »

Edson

  • Hero Member
  • *****
  • Posts: 1054
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #1 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  %).
Lazarus 1.6 - FPC 3.0.0 - x86_64-win64 on  Windows 7

Leledumbo

  • Hero Member
  • *****
  • Posts: 8111
  • Programming + Glam Metal + Tae Kwon Do = Me
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #2 on: January 28, 2016, 11:15:59 am »
Well, I have always been saying Lazarus/Libraries is poorly documented. But always people here, send me to read Delphi docs  %).
Not always, I also ask people to be the documenter as well ;)

marcov

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 7493
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #3 on: January 28, 2016, 11:18:14 am »
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

  • Sr. Member
  • ****
  • Posts: 266
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #4 on: January 28, 2016, 12:33:13 pm »
Load Delphi(3?)
Put the cursor on a keyword
press F1
Analyse the page you get carefully.

That is the documentation needed.



marcov

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 7493
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #5 on: January 28, 2016, 12:53:22 pm »
Load Delphi(3?)
Put the cursor on a keyword
press F1
Analyse the page you get carefully.

That is the documentation needed.

If you noticed differences, why didn't you submit a patch or bugreport for them?

A mentality change, that is what needed.

ArtLogi

  • Full Member
  • ***
  • Posts: 144
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #6 on: January 28, 2016, 01:59:00 pm »
I'm a bit unsure how I should shape this, but what I did try to say is that there is no self regulating infrastructure for the documentation (what I know and if there is, it is poorly "advertised" itself.), which would allow "open source" style of documentation evolution, like wiki, but more hierarchical by structure. My idea for that is obviously that there would be this backbone structure of these tutorials documents and users then can broaden the subjects and add more stucture, but the backbone system will lead and instruct the contributors so that the "documentation tree" will keep its structure informatic and easy to use. This for distributing the workload because as we know this is volunteer work.

How that could be build? For that I have no definite answer as I have no experience of anything like open source development or shared document writing. Somekind of instructing (and supervising) documentation core team wouldn't be a bad thing. Somekind of semistandard page and chapter structure template with some guidance commentary might be good for wiki.

The critique of the sidetracking documentation is another story, based on my own observations from the last few weeks.

This as a quick reply, I need to return in better time.
« Last Edit: January 28, 2016, 02:00:36 pm by ArtLogi »

jack616

  • Sr. Member
  • ****
  • Posts: 266
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #7 on: January 28, 2016, 03:06:03 pm »

If you noticed differences, why didn't you submit a patch or bugreport for them?

A mentality change, that is what needed.

I agree - what "bug" are you talking about?

ArtLogi

  • Full Member
  • ***
  • Posts: 144
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #8 on: January 28, 2016, 03:35:38 pm »
Well, I didn't manage to start todays work  >:( Instead I find myself reading the mediawiki main page and trying to figure out the freepascal wiki .. It is so old version, 10 years old mediawiki engine, judging from the editor look..

This how the mediawiki editor looks like today .. much more productive:
https://www.mediawiki.org/wiki/Project:Sandbox?veaction=edit

Also something like category tree templates would be good for somepages:
https://www.mediawiki.org/wiki/Extension:CategoryTree#The_.3Ccategorytree.3E_tag

..Need to try to contact to wiki admin.

marcov

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 7493
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #9 on: January 28, 2016, 04:03:14 pm »
I'm a bit unsure how I should shape this, but what I did try to say is that there is no self regulating infrastructure for the documentation (what I know and if there is, it is poorly "advertised" itself.), which would allow "open source" style of documentation evolution,

The normal documentation is also open source, all code is available open source. but just like with the source code, only people with a commit bit can finalize a change. Luckily the documentation is textformat so you can edit locally and submit patches in good open source tradition.

And for the rest there is the wiki that is truely open.

It is just not a social website, but the last time I checked, I can't go to Oracle, Microsoft, Python or PHP and change the maindocs there either.

E.g. Where is the edit button here?  https://docs.python.org/3/distributing/index.html ?

Quote
My idea for that is obviously that there would be this b
ackbone structure of these tutorials documents and users then can broaden the subjects and add more stucture, but the backbone system will lead and instruct the contributors so that the "documentation tree" will keep its structure informatic and easy to use. This for distributing the workload because as we know this is volunteer work.

I don't know any major projects that work that way. Most smaller projects resort to a wiki, with some desperate people trying to maintain structure and mediate
in astrodurf, usually fighting a losing battle.

Quote
How that could be build? For that I have no definite answer as I have no experience of anything like open source development or shared document writing.

To my best knowledge many smaller projects use wikis, and larger projects use non publically editable documentation systems with patches over ticketing systems. Just like FPC. In even larger projects there are fulltime employed docworkers somewhere.

Quote
Somekind of instructing (and supervising) documentation core team wouldn't be a bad thing. Somekind of semistandard page and chapter structure template with some guidance commentary might be good for wiki.

The critique of the sidetracking documentation is another story, based on my own observations from the last few weeks.

This as a quick reply, I need to return in better time.

I'm not volonteering for anything wiki. I never saw quality wiki docs, specially not in the programming areas. They all labyrinths are without heads or tails. It is not something that works, it is what is done when nobody really wants to write docs, in the hope that something magically falls together.

Usually maintenance spikes, quality contributions are low, and people that should be working on docs are actually mediating turf wars and vandalism in the wiki
« Last Edit: January 28, 2016, 04:05:25 pm by marcov »

skalogryz

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 2280
    • havefunsoft.com
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #10 on: January 28, 2016, 04:39:09 pm »
I'm not volonteering for anything wiki. I never saw quality wiki docs, specially not in the programming areas. They all labyrinths are without heads or tails. It is not something that works, it is what is done when nobody really wants to write docs, in the hope that something magically falls together.
I'd say that's a normal case for (unfunded) open-source projects. Non specific to a wiki. 
In the end, wiki is just an editorial tool (with a high flexibility for better or worse).

What do you usually for creating documentation? More specifically how do you define heads and tails?

Usually maintenance spikes, quality contributions are low, and people that should be working on docs are actually mediating turf wars and vandalism in the wiki
Luckily due to low popularity of (free) pascal as well as people not willing to actually write wiki, doesn't seem to turf wars be happening.
Patron Cocoa Widgetset development https://www.patreon.com/skalogryz

sysrpl

  • Full Member
  • ***
  • Posts: 230
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #11 on: January 28, 2016, 05:02:39 pm »
I've started a learning section here:

http://www.getlazarus.org/learn/

I will be adding a lot of content to it over the next month including video tutorials. If anyone feels the like contributing or editing you can use the edit page link at the top of every page to submit content. My back end tool shows me the diffs where I can easily merge your edits into any pages.

ArtLogi

  • Full Member
  • ***
  • Posts: 144
Re: Documentation / tutorials need improvement (was: Object Pascal deline?)
« Reply #12 on: January 28, 2016, 05:14:15 pm »
This is dangerous, I mean the information is splitting and spreading while everyone have good attentions, the outcome is even more clustered and hard to digest with many portals.

@sysrpl, I like your getLazarus.org page, since it does have rather good structure what I have been reading it and it does have more modern touch on it. It is good portal for promoting, that is for sure.
« Last Edit: January 28, 2016, 05:21:07 pm by ArtLogi »

Graeme

  • Hero Member
  • *****
  • Posts: 1430
    • Graeme on the web
Re: Documentation / tutorials need improvement (was: Object Pascal decline?)
« Reply #13 on: January 28, 2016, 08:26:54 pm »
So if the documentation is so bad [which I don't think it is], then stop complaining and start creating these "ultimate" tutorials. FPC, Lazarus etc are open source project - driven by the community. YOU are part of that community, so why not help out where you see a gap. I personally think the FPC documentation is very good, and YouTube has tons of Lazarus videos available.

Either way, I'm busy authoring a step-by-step ebook for application development with fpGUI. I started by introducing the framework, then introduce a very basic application, then introduce event handling etc etc and start building up the complexity. I've grouped the chapters into two sections: Basic and Intermediate (Advanced might be added later, if there is a need). So if you feel you are not a beginner, then jump in at the level you think is appropriate to you. The book is open source (included in the fpGUI repository). I welcome others to use the same Table of Content to produce a LCL version.
--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

vicot

  • Full Member
  • ***
  • Posts: 114
Re: Documentation / tutorials need improvement (was: Object Pascal decline?)
« Reply #14 on: January 29, 2016, 02:02:43 am »
Just a quick remark about what has been said: the observations about the lack of sufficient documentation/tutorials were not intended as criticism of anyone (at least as far as I am concerned), but as an encouragement for the community to remedy to this gap. Some steps in the right direction have already been taken, like the website that promotes Lazarus (getlazarus.org), which is GREAT. Kudos to its developer, keep it up!!
We should all try our best to contribute to such efforts, even if just by making publicity about them. However not all of us have the technical ability to participate practically in preparing the documentation.

We are all on the same side, and with the same objective (namely, supporting FreePascal and Lazarus). Let's not squabble among ourselves.
« Last Edit: January 29, 2016, 02:09:15 am by vicot »