Re: [Lazarus] Suggestion for TRadioGroup documentation

OK, I was just hoping for a sentence or paragraph to be added to the documentation. In HTML you group radiobuttons by giving every button in the group the same name but different values. I started with a tgroupbox then went to a tradiogroupbox when it didn't work. Still got -1 for ItemIndex so I defined some with tstrings and got a duplicate set, but itemindex works on those. Aha! But a radio button that doesn't belong to a group isn't much different than a checkbox.

I agree with most things said about documentation except that nobody has time to read it all. And it can change, so you have to keep rereading. Being a multilingual project complicates things too. When I started in Linux I read (and printed) howtos, took them very seriously. But by the time I got around to doing what I was reading about I found the howtos were years old and almost worthless.

I don't have my internal help working yet, and it may not be as good as Delphi's when I do. So I Google a lot. Documentation that looks like it came out of doxygen turns me off because so much of it's bad. Good internal help may be a thing of the past.

I've seen bad documentation that looks like it was written by fledgling technical writers and tells you obvious things. I agree, the programmer is the ultimate reference/authority but I've had to document projects and didn't enjoy it either. So I think some compromise like the newbie tech writer writes it and the programmer checks/edits it might work. How that works in a multilingual environment I haven't a clue.

Really, I'm sort of trying out Lazarus again. A year or so when I tried it last I kept getting an error which, from Googling, I thought came from the fact that OpenBSD basically has no working locale and little interest in it. So I gave up on using it. Now I find it's better, and when I get the error doing a "clean up and build" seems to always get rid of it. "Illegal character in format string" I think it was.

Alan Corey wrote

OK, I was just hoping for a sentence or paragraph to be added to the documentation.

Welcome to open source.
Instead of complaining here and wasting everybody's time, you could have improved the documentation yourself and provide a patch.

You also happened to trigger J?rgen Hestermann's passion to bash Lazarus developers with whatever excuse, but that is not your fault. We should impose some rules for such people. From experience I know it can escalate indefinitely. Such people feel they have right to use a free tool and then complain about how bad service they have got and how the developers should do more and better for serve him.

One more thing:
Copying the whole e-mail thread history in your message is bad. Please copy only small snippets that you want to answer to or comment.

Juha

Il 08/04/2016 21:13, Juha Manninen ha scritto:

Welcome to open source. Instead of complaining here and wasting everybody's time, you could have improved the documentation yourself and provide a patch.

In principle you're right. However you should take into account some other factors.

Frequently users do complain when a problem arises which they are unable to solve by themselves.

Asking them to provide a patch doesn't help too much.

On the other hand there is something that could be done to improve the situation, and to encourage contributors to help improving the documentation.

There's a number of core developers, which set the rules of the game, by evaluating contributions, supervising them and accepting or rejecting depending on their view of what the product should look like.

It wouldn't be unthinkable that a contribution be evaluated also in terms of documentation. Appropriate comments in the source code make almost easy to generate a good documentation.

An answer such as: "Your patch is good, it adds a desirable functionality, but without proper documentation, nobody will be able to take advantage of it. Please add some concise comments on variable and procedure usage, and we will be glad to commit it." would do a lot of good, IMHO.

Should this become a general rule, the situation might strongly improve with time.

Just my 2 cents.

Giuliano

Giuliano Colla wrote

An answer such as: "Your patch is good, it adds a desirable

functionality,

but without proper documentation, nobody will be able to take advantage

of it.

Please add some concise comments on variable and procedure usage, and we will be glad to commit it." would do a lot of good, IMHO. Should this become a general rule, the situation might strongly improve

with time.

Agreed :-) In reality though we shouldn't exclude patches just because they lack the above. We should only be encouraging decent documentation, not enforcing it.

"Yay, we've got a patch that finally fixes that annoying TreeView issue, but rats, we can't commit it because those variables aren't sufficiently documented"

Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/ecedd2f7/attachment.html>

Giuliano, you have contributed code yourself. I did not expect such nonsense from you.
Your own code was equally good with other Lazarus code. It had about the same amount of comments which was fine.
Rejecting patches because they don't have enough comments would have only negative effects.
Well written code does not need much comments.
"Comments are like a deodorant masking the smell of fishy code that could be improved."
as sourcemaking.com so well describes:
https://sourcemaking.com/refactoring/smells/comments

So, your suggestion would only reduce contributions without any benefit. Typically such ideas come from people who only want to bash the developers. "Do this and that and then contributions start to flood in." For some reason those people have no intention to contribute anything themselves...

Poorly written patches are already rejected and their authors are guided how to improve them. Things are in order in that front. Most patches now get accepted or rejected reasonably quickly. Why all this valuable work from me and from other developers is ignored?

Juha

Giuliano Colla wrote

An answer such as: "Your patch is good, it adds a desirable functionality, but without proper documentation, nobody will be able to take advantage of it. Please add some concise comments on variable and procedure usage, and we will be glad to commit it." would do a lot of good, IMHO. Should this become a general rule, the situation might strongly improve with time.

+1

Il 09/04/2016 14:03, Juha Manninen ha scritto:

Why all this valuable work from me and from other developers is ignored?

Because without a minimal amount of documentation all this valuable work risks to be useless, because:
- nobody except a few core developers know of its existence
- nobody except the developer itself knows how to use it

Giuliano

Giuliano Colla wrote

Because without a minimal amount of documentation all this valuable work risks to be useless, because: - nobody except a few core developers know of its existence - nobody except the developer itself knows how to use it

from OpenHub (which for some reason stopped tracking lazarus a year ago) In a Nutshell, Lazarus...

- ...
- is mostly written in Pascal
<https://www.openhub.net/p/lazarus/analyses/latest/languages_summary> with an average number of source code comments
<https://www.openhub.net/p/lazarus/factoids#FactoidCommentsAverage>

You say minimal, code analysis says Average.
I also disagree that the wiki contains minimal content.

Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/63408e98/attachment.html>

Giuliano Colla wrote

Because without a minimal amount of documentation all this valuable work risks to be useless, because: - nobody except a few core developers know of its existence - nobody except the developer itself knows how to use it

LCL is documented more or less.
I guess you mean the IDE internals are not documented. It is true, their documentaion has low priority compared to public libs. I also would love to see high level diagrams and other docs about the IDE. Like always, somebody must do it.
Maybe you ... :)

Juha

Michael Thompson wrote

You say minimal, code analysis says Average.

Comments are overrated.
If you think of them as "deodorant masking fishy code" then less comments is better.
What would really help are high level documents of IDE internals. Diagrams and textual description. My favorite diagram is Sequence Diagram because it shows both actors and cronological order. Such documents would help only (potential) developers of the IDE, but that is already very useful.
Why is it not done?
I think because they help only initially when learning certain code. The same understanding comes from reading and browsing code, but it takes longer time.
That's why the developer who knows the code has only little motivation to draw diagrams.
Anyway, after the initial understanding is got, everybody must read the code. Thus diagrams are not necessary but the sure would make the project more attractive to new potential developers.

Are you good in drawing diagrams?

Juha

Il 09/04/2016 16:22, Juha Manninen ha scritto:

My comment was about the portions of your or other's valuable work (IT IS VALUABLE, you can say it loudly) which aren't documented, or are poorly documented. (the *less* sections of the *more or less*) And to stress to developers (myself included, I'm as documentation lazy as anybody else around here, maybe more..) the importance of letting other people understand exactly what it's been done, so that it is widely used, giving the only possible reward to Open Source developers: their work is not just an idle exercise, but it is actually used.

There is a specific moment in the development cycle when a developer can find the time to write some documentation: it is between the submitting of his patch/implementation/enhancement/whatever, and the testing from others. In this stage it would be unwise to change something before receiving some feedback, and the developer has still a fresh memory of what he's done. If he is encouraged to do it, chances are good that he will comply. And chances are also good that while browsing what he's just done, he will spot and fix a couple of bugs....

Giuliano

Juha Manninen wrote

Are you good in drawing diagrams?

:-) Me? I'm useless at drawing I contributed to mplayer, I came up with three tactics of documentation - expanded comments in code,
http://wiki.freepascal.org/TMPlayerControl and a demo project that covered every thing I could think of.

When people ask for help, it's the demo project I point them to :-)

My personal opinion? Code! Code always has the answer :-)

Mike
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/66defe0e/attachment.html>

Il 09/04/2016 16:41, Juha Manninen ha scritto:

Comments are overrated. If you think of them as "deodorant masking fishy code" then less comments is better.

Comments may help to clarify what is obvious to you at the moment of writing, but not to anybody else, and maybe even to you some time later.

You are right that usually commenting code is not very useful. Well written code is most of the times self documenting, even if *most of the times* doesn't mean *always*.
Commenting variables, on the other side, may be crucial for the understanding, and not always names are or can be self explanatory. The same holds true for procedure parameters, and function results.

I remember reading long time ago the assembler source code of an Intel Real-time nanokernel, where I couldn't grasp what a "crflag" variable was used for. It appeared to have to do with some kind of data protection but it was rather unclear.

Then the same nanokernel was rewritten in PLM which allows for longer identifiers, and "crflag" was renamed "CriticalRegionFlag": suddenly everything became clear. The purpose and the usage of the flag became obvious. If the declaration of crflag had carried a short comment "critical region flag", the assembler code would have been much clearer.

Giuliano

There already have been lots of discussions on a reform of the help system that (e.g. by using a single managed Wiki exclusively as the root of the articles) is open for volunteers to provide fixes and additions and actually see "live" what they did without waiting for the next Lazarus release.

AFAIK this is a too great task to be considered doable in near future.

-Michael

Michael Schnell wrote

(e.g. by using a single managed Wiki exclusively as the root of the articles)

Wiki's are only good for knowledge base - adding random thoughts as pages - loosely linked together by cross-links. It is terrible as a help format/medium.

The other problem with the wiki. Too many hands in the pot and no control of who edits what. So somebody could add rubbish or inaccurate information, and the next person will read that thinking it is correct.

Also there is no wiki help per Lazarus release. eg: Can I see the wiki help for when Lazarus v1.0 was released? NO!

is open for volunteers to provide fixes and additions and actually see "live" what they did without waiting for the next Lazarus release.

Yes, it's called "fpdoc" and have been around for years! It takes a minute or two to generate your own help in whatever format you prefer - HTML, CHM, INF, TXT etc. Users can contribute by supplying documentation patches. It also solves all the above mentioned wiki problems.

Regards,
- Graeme -

There is a simple fpdoc editor built-in the IDE for identifiers (View / FPDoc Editor). It allows even lazy programmers to easily add a sentence about an identifier. Just place the source editor cursor on an identifier, write a short explanation in the fpdoc editor - done. It also allows to create fpdoc entries for your own projects/packages with a simple click.

For topics and examples you can use LazDE.

See here:

http://wiki.freepascal.org/FPDoc_Editor

Mattias

Graeme Geldenhuys wrote

Wiki's are only good for knowledge base - adding random thoughts as pages - loosely linked together by cross-links. It is terrible as a help format/medium.

While I do see your point I can't think of any other authoring system that might be able to allow for possible volunteers to do contributions (as has been the wish of some previous posters).

Of course strict rules would be needed to be defined and (at best automatically) be enforces to allow Wiki pages to (automatically) be converted to help content. That is why it's obvious that setting up such a system would be a lot of work and would bind a lot of manpower for a decent amount of time. So supposedly no chance. :-( .

-Michael

Graeme Geldenhuys wrote

Yes, it's called "fpdoc" and have been around for years!

Of course I do know this.

I did play with it.

Its a kind of "Write only memory": you don't see what you did. (Unless you go a very hard way to be able to compile the complete help system on your local PC.)

It's a perfect means to shy away any volunteers.

-Michael

Michael Schnell wrote

that might be able to allow for possible volunteers to do contributions

As Mattias mentioned, Lazarus IDE even includes a fpdoc editor built-in. You can't get easier than that! You don't even have to leave the IDE. Then simply generated a patch and post it to Mantis (like all other contributions).

Somebody will review the patch and apply it as soon as possible. At least that way the documentation gets a review and can be rejected if there are mistakes.

Currently with the wiki, rubbish can be added and no review is done! The wiki is the best of the worst.

Regards,
- Graeme -

Michael Schnell wrote

Unless you go a very hard way to be able to compile the complete help system

What's so hard about this:

fpdoc --project=lcl-docs-project.xml --format=html or
fpdoc --project=lcl-docs-project.xml --format=chm
or
fpdoc --project=lcl-docs-project.xml --format=ipf
or
fpdoc --project=lcl-docs-project.xml --format=rtf

You don't need all those *.sh or *.bat scripts, makefiles or custom console tools any more. FPDoc has made it dead simple to generate documentation with the help of a fpdoc project file. Project file support has been around since FPC 2.6.2 or 2.6.4 - not sure which.

[...few seconds later...]

To my surprise, it seems Lazarus doesn't include a fpdoc project file for LCL. I'm happy to contribute mine. I'll submit it to Mantis now. In fact I see the <lazarus/docs/ directory is full of obsolete scripts (*.sh, *.bat, *.pl, makefile etc). They really should all be removed and replaced by a single fpdoc project file.

Regards,
- Graeme -

[...] Currently with the wiki, rubbish can be added and no review is done!

You could say the same for the fpdoc files.

IMO review means someone else reads it and reports/fixes errors. This is done for both though in different form.
The Wiki has a problem with spammers though.

Mattias

Graeme Geldenhuys wrote

Currently with the wiki, rubbish can be added and no review is done! The wiki is the best of the worst.

Of course (and as I said) the wiki for the help needs to be managed. The writer needs to see what he did (at best integrated in the help view of his local IDE), but for others to see (i.e. a release) one of the "powers" need to review it .

Of course the standard Wiki software does not provide the necessary features (such as only "personal" update until review/release, enforcing certain rules for providing decent conversion to the target help text formats.

That is why I said: a lot of work.

No it does not make much sense to discuss this here, unless somebody with a lot of spare time stands up and says "I'll take it on" ;-) .

- Michael

Mattias Gaertner wrote

> > Currently with the wiki, rubbish can be added and no review is done! You could say the same for the fpdoc files.

Uh? I don't believe that anybody takes a patch from Mantis and applies it blindly without actually looking at the patch. If they do, that is very sad news for the Lazarus project.

Patches via Mantis has infinitely more chance of being reviewed (at minimum glanced over once by a trusted expert) than the 10's or 100's of changes made in the Wiki every day.

Regards,
- Graeme -

Graeme Geldenhuys wrote

What's so hard about this:

Maybe you do remember that (with your help) I once tried to contribute to the fpc help.

I failed to do this in a decent way (I finally sent in the text per mail, maybe it had been included in the next release of the fpc help (at least a year later). I id not dare to check.

I'm not going to try to contribute to the help until I'm retired (which is not that far away ;-) ).

-Michael

Michael Schnell wrote

Maybe you do remember that (with your help) I once tried to contribute to the fpc help.

1) If you can type, you can contribute.

2) The other thing you need to know:
http://wiki.freepascal.org/Creating_A_Patch

That's it!

mail, maybe it had been included in the next release of the fpc help (at least a year later).

FPC documentation is timed with FPC releases. So that only happens one a obviously you will not see updates sooner. The Lazarus project releases much more often, and we are talking about Lazarus documentation here.

Regards,
- Graeme -

Graeme Geldenhuys wrote

... and we are talking about Lazarus documentation here

Of course at this location we are.

But a documentation decently usable by the Lazarus "customer" needs to cover (at least) IDE, LCL, the language, the compiler, RTL, and the most common packages.

Anyway: just dreaming. Volunteer driven systems never get there.

-Michael

No one is applying blindly patches and no one adds stuff blindly to the wiki.
I meant that the developers are humans. They are not experts on all topics. Buggy patches has been applied.
The more people look over it the better. This is true for both fpdoc and wiki.

Patches via Mantis has infinitely more chance of being reviewed (at minimum glanced over once by a trusted expert) than the 10's or 100's of changes made in the Wiki every day.

I doubt these numbers. Especially since infinitely is not a number. ;)

Mattias

Michael Schnell wrote

Anyway: just dreaming. Volunteer driven systems never get there.

FreeBSD has. So there is hope for others. ;-)
FreeBSD's documentation is impressive and complete. Not only do they have very extensive "handbook" documentation in different languages, they have published books detailing the intricate details of the OS kernel, file system, boot process etc.

Regards,
- Graeme -

Graeme Geldenhuys wrote

FreeBSD has.

OSX is based on BSD,

So maybe this is not really Volunteer driven :-)

-Michael

Michael Schnell wrote

OSX is based on BSD, So maybe this is not really Volunteer driven :-)

Apple had nothing to do with it. FreeBSD's documentation existed long before OSX saw the light of day.

Regards,
- Graeme -

Nobody disputes that. If you want to sacrifice content to easy access on principle, then that would definitely be the way to go.

It is the conjecture that the content will actually improve because of it that I find highly doubtful.

True.

This is true for both fpdoc and wiki.

No. Wiki has patches applied without any kind of post-commit filter. So fpdoc is first order (at worst), and wiki 0th order (at best).

Sorry, can't remember any patches, so it can't have been too serious!

Marco van de Voort wrote

It is the conjecture that the content will actually improve because of it that I find highly doubtful.

Absolutely agreed ! An unmanaged Wiki would be highly dangerous. A complete managing system on top of the standard Wiki software would be required.

-Michael

Marco van de Voort wrote

> Maybe you do remember that (with your help) I once tried to contribute > to the fpc help. Sorry, can't remember any patches, so it can't have been too serious!

As said: I (unsuccessfully) tried.

-Michael

2016-04-09 12:20 GMT+02:00 Giuliano Colla :

Sorry to reply so late but here you have hit the core of the question. Many times I've tried to do something that failed in a miserable way (i.e. miserable/hobbist/old programmer). BTW, contribute to an open source project can be done as programmer, tester, artist, disigner, marketter etc. So if someone has a good idea to improve the project but is not able to implement it, I think there is nothing wrong with proposing it here without this being interpreted as a request that the core developers must do. If anyone knows how to do it, and overall want to do it, well, otherwise it goes on and nothing changes. Anyway I want to say thanks to all of you, old and new developers
Salvatore

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160413/822e0d1f/attachment.html>

So you can't operate a text editor?

And an investment in manhours to make that happen that IMHO will never be earned back.

Marco van de Voort wrote

> As said: I (unsuccessfully) tried. So you can't operate a text editor?

I unsuccessfully tried to create an environment that lets me see the modified help text (we already did discuss this some years ago).

AFAIR, I did send (you ?) a modified help text for "CheckSynchronize()" (in fact a "patch" as it was the complete small chapter). (Of course this was not for the Lazarus help files, but RTL.)

Maybe it now is included.

-Michael

Marco van de Voort wrote

And an investment in manhours to make that happen that IMHO will never be earned back.

I can't contradict.

But in fact "earned back" is extremely hard to define when comparing two far distant edges of a non-profit project.

-Michael

It is very very simple for a non-profit/OSS project: more man hours earned back than those which were invested.

Florian Kl?mpfl wrote

It is very very simple for a non-profit/OSS project: more man hours earned back than those which were invested.

that would completely ignore the interest of the users of the project. (Which in commercial projects can be measured in the revenue.)

So not a friendly

No, the equation includes everything along with everybody's interests.

Example:
You spend X hours to write documentation for A that saves Y hours to Z users that otherwise had to study the code.
Then you can compare X to Y*Z.

Michael Schnell wrote

So not a friendly seem to have misunderstood Florian's statement ;)

Ondrej

That was my initial proposal leading to "extremely hard to define", as (due to no intended and hence measurable revenue) the developers don't have any idea about the count of users and the effort they need to get their work done.

As an extreme you would say: no documentation at all is best, as that means no hours to create it and there supposedly will be at least a single user who is able to make some small benefit from the project and hence the positive ratio is infinite .

-Michael

This only is right, if the user who decides to invest in writing documentation, only writes it, and then uses it once, and then doesn't care any more.

Which I'd say, is /hardly ever/ the case ?

Same with the readers of the docs,
can you remember EVERY content of EVERY doc you ever read, every time you wish to use the knowledge contained therein ?

You have a chance of remembering by heart what you read, at least '7' times, if you wrote it yourself

(7 is just arbitrary number here; although not far from reality of creating 'written works', that I read of having at least 8 revisions before considered stable & good style ),

while consumers of the docs need to read them more times to remember.

-L.

-Michael

You use the word /define/ wrongly. Please see
https://en.wikipedia.org/wiki/Definition . Florian gave you the exact definition.
You probably meant it is hard to /estimate/ the unknown parameters.

Furthermore, it is wrong that a user can judge better than a developer. The quality of a judgement doesn't depend on the role of the person.

As an extreme you would say: no documentation at all is best, as that means no hours to create it and there supposedly will be at least a single user who is able to make some small benefit from the project and hence the positive ratio is infinite .

No, you are wrong. The "resulting benefit" is not taken into consideration. You compare the times you need to get to the "resulting benefit" once without the work X (in my example "without documentation") and once with the work X (in my example "with documentation").

Ondrej
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160418/581966c8/attachment.html>

It's not the ratio (quotient) that is of relevance here but the difference.

True, but that is not the same as not being able to contribute.

You can submit the textual patch just fine.