This thread seems to have changed into one that discusses the provision of Help for Lazarus, so I'm going to start a new thread.

I am currently trying systematically to produce documentation for all the classes in the LCL, and the tool that I have found most useful is the FPDoc editor in the Lazarus IDE. There are a few things it does not readily address, such as the provision of a short description for the Unit files themselves - I have usually done this by hand, and the problem of duplicate declarations - FPDoc usually constructs documentation files from the last delaration in the pascal source file, so if the XML tags have been attached to a forward declaration, they often get missed, or if there are alternative versions of a declaration, onely one of them gets picked up.

However, by and large, the FPDoc editor is an excellent tool, and I would encourage anyone trying to produce Help to use it as the first resource.

As well as providing detailed descriptions of all the classes, procedures etc in the Lazarus code, we need to produce a lot of How-to type documentation, and this process is still in its infancy. There is a lot of good stuff in the wiki, but it is not very systematic. Some of the developers are writing a Lazarus book, and we should encourage this to form the basis of a good manual. We need lots of ideas, and a lot of work needs to be done. All offers of assistance will be welcome.

Chris

As an exercise, I have copied the material from the Lazarus Wiki page "AutoSize" into a Topic in Controls.xml; I performed the editing by hand in a text-editor, and the basic one-for-one translation took me about an hour. I then had to make a number of corrections and annotations, taking about another half-hour.

Obviously the Wiki document could be automatically parsed and translated into the XML format required for FPDoc, but we would still need to exercise editorial control over the actual material, to ensure that it made sense, was clear and consistent with the other documents etc. I'm not sure that the FPDoc XML format is the ideal for "How-To" documentation, and like the idea suggested by Graeme for a plain text-file format which could be treated in a variety of different ways.

At present both the FPDoc editor in the IDE and the LazDE stand-alone app have problems which make them less than ideal for producing "How-To" documents (I am filing bug reports as appropriate), so any approach that leads to the construction of IDE and other documentation on usage would be welcome.

Regards - Chris

2009/8/20 Chris Kirkpatrick :

FPDoc XML format is the ideal for "How-To" documentation, and like the idea suggested by Graeme for a plain text-file format which could be treated in a variety of different ways.

That is the same issue I found. My first thought was also to use FPDco, but FPDoc is not suitable for how-to or application documentation - it was designed for class documentation and that it does very well.

I think AsciiDoc is a very nice solution. Easy to edit, can be used as-is, or easily parsed and processing into other formats. The original AsciiDoc (python) application also supports various macros. One of the is the "include" macro, which means you can split or share documentation. Something like a "book". Each chapter is a text file and the book.txt file contains a bunch of Include macros which pull in the chapters.

The more I am playing with AsciiDoc the more I think it is a very suitable help format. I also want to play around with the THelpDatabase component and implement one for AsciiDoc content with an simple viewer, just to see how it could tie into applications and context sensitive help.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

One thing that has been mentioned a couple of times in the past, is the ability of searching for entries.

More thna once this has been put down to a simple text search:
- web based docs can be googled 9or whatever your favourite search is)
- text base can be searched a la "find in files" (grep)

That is more than insufficient.

That is why the docomentation on the wiki is so oft judged as having no info on anything. Searche return plenty of matches, but even if you are lucky and the right page is somewhere in the list, you still have to search a lot of pages by hand.

Words in documentation often have special meaning, and often more than one. They must either be marked in hte text, as being a keyword X, or listed in a separate keyword list

Example;

- Frame (also in plural Frames must much the same pages): There are at least 3 ways it can occur in the doc
1 - TFrame => visual form inheritance
2 - Stack frame
3 - just the plain English word.
If you search for it, you should be asked if you mean 1 or 2.

Not to speak of related topics that may want to be suggested...

My 2 cents
Martin

2009/8/21 Martin :

That is more than insufficient.

Speaking about plain text docs (Asciidoc). keywords can be generated from them or maybe a more informed keyword file could be built manually. Something like meta-tags used in blogs or web page headers. Alternatively, we can look how fpdoc generates keywords and indexes and use something similar.

As long as we can start having help in a offline (and possible online) format, that would be a good push in the right direction. Currently wiki docs is not helping and is in the wrong (non-portable) format.

In this case search for "frame" has a 'complete word', which should then ignore 1 and only return 2 as a result.

But yes I get what you mean. Extra keywords or meta-tags for each document pages would be helpful. What does fpdoc do in this regards?

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

I don't know, but don't think fpdoc currently has that feature.

The problem is that you cannot trust the user to search for "TFrame" or "StackFrame" or TException", the user will search for the plain english word frame or exception. And that will bring a lot of extra results.

So its to steps:
- a list of translation: ask the user what frame he wants
- inside the page, make sure that the plain english word is not taken in account. With Tframe this si solved by the first step, because the actual search will be for "TFrame" and therefore miss the simple word frame. (yet with "function" the pascal keyword is equal to the english word)

As long as we can start having help in a offline (and possible online) format, that would be a good push in the right direction. Currently wiki docs is not helping and is in the wrong (non-portable) format.

Agree.
but the discussion so far mostly went about portability. If a decision is made it should address the search issue too.

otherwise you could just download all wiki pages as html, and rewrite the links to point to the local pages. there are plenty of programs that can do exactly this. Of course the downloaded version would no longer have the "search button" since that is server side. But it would be portable. Simple html files on your local disk.

complete word would also ignore the plural "frames" which you do not want.

But it was never about finding 3. It was about explicit search for 1 or 2

But yes I get what you mean. Extra keywords or meta-tags for each document pages would be helpful. What does fpdoc do in this regards?

Another thing about the help. And i feel bad about saying this, because I really appreciate the effort that was made. And criticizing it without having contributed seems all wrong.
Never the mind, since we talk about it, I feel it should be mentioned

Some of the documentation still reads like a mockup, providing not more help than looking at the function itself.
I am trying to give an example how I think it could be improved. Just as a base for discussion

If I call help on a method from the LCL, I probably can look at the source code, especially if it's just a few line. So instead of an english representation of the pascal code (which may not provide any new info to me) I probably seek something like:
- what is it used for
- in which context is it used
- what happens / what else does it affect
- or why is it needed

example
http://lazarus-ccr.sourceforge.net/docs/lcl/forms/tcustomform.notification.html

this is what a look at the code immediately reveals. Maybe better:

"Called when the action-list linked from the form is destroyed, so it can be removed"

First to be fair: a more proper explanation is given on the base-class. (see also)
This is the first problem: how much of the base class to repeat? Or how many links does the user have to follow to find what he seeks.

Many user will judge the help by the first page they get. Only if that page gave them some information they may seek further. The problem is especially if you search for a specific functionality, of which you do not know the name. So you press F1 on 2 dozens different methods, that may or may not be what you wnat (just because they sound as if they could). If you get 2 dozens times to a page, where you just have to follow another link ....

A short reiteration would be very helpfull:
(the wording needs some more effort, this was written on the fly only)

Called to notify the Form that another control has been destroyed (or otherwise removed). [[ comment on a form ther is no insert operation, or is it? make it "removed or added" ]]
The form checks if it refers to this control via it's "action list" and clears this property if necessary.
It passes the information on to it's parent [link
TControl.Notification] which can check for other properties that may be affected.

and then the See also link.
- The see also link could also contain a link to TControl which is the next highr class to have this function (and provides information about further properties that may be cleared)
- the see also could repeat some of the links on
TComponent.Notification, such as the link to FreeNotification or TOperation (anyway included in the declaration)

2nd and this is just my humble opinion (IMHO): "calls inherited Notification,"
I do not think this is very usefull info (but I am aware that other may think so) or more to the point, the representation is not very good. See my example above.

Best Regards
Martin

Martin wrote

Another thing about the help. And i feel bad about saying this, because I really appreciate the effort that was made. And criticizing it without having contributed seems all wrong. Never the mind, since we talk about it, I feel it should be mentioned

thank you very much, martin, for posting that... i have been fighting with myself for a long while how to approach the topic... many things that are documented are pretty terse and do not carry easy to understand explanations of their who, what, why, where, and when aspects... yes, even some "good" book on programming topics are hard to understand but still... perhaps a step back to the early days and simpler times is needed? that and maybe someone who understands geek but doesn't speak geek should be involved to "average joe" the documentation?

i also hope that this current effort on developing a help system also carries over to the Lazarus and FPC projects so that they do end up with good offline documentation that budding programmers can easily understand, follow and learn from...

Also: every author has a different opinion about appropriate keywords.

I found it essential that a central repository (database?) holds a documentation structure and keyword list(s), with a short definition of each entry. This repository should be updated by a documentation team, so that it remains consistent. Every piece of information has to be assigned keywords (attributes, tags) from that repository, so that it can be inserted in the right place.

This is one aspect, to be covered by above structure. When we collect enough search "patterns", it should be possible to identify a top level list of question types, along with a list of possible result categories. E.g. a search for "identifier" <name> can be qualified with any of
- short description
- long description, doc(s)
- implementation details
- declaration/definition (in unit...)
- compatibility/platform/widgetset, library
- bugs and problems
- examples, workarounds
- feature requests
- group (structural? functional? by task?)
- related
- overviews
- backgrounders
- tutorials, books
- author

The "group" result should be unique, otherwise above question about the meaning (which of the applicable groups is meant). Same for declarations in multiple units.

Every entry should have a "kind" and according attribute(s), e.g. declaration: identifier:type in unit...
description: topic/identifier
example: task, related to...
overview: group, topic, related to...
backgrounder: related to...

An attempt to classify a couple of entries in the various information sources (units, libraries, fpDoc, wiki, Delphi, bug tracker, feature requests...) should return enough material for the construction of a structural skeleton. Possibly the sources can be scanned (indexed) automatically, resulting in a list of entries that wait for a classification and assignment of attributes.

For both the classification of entries and the later search, I could imagine a hierarchical representation of the applicable keywords or attributes. The first column contains the top level hierarchy, and a selection from a column fills the next column with applicable qualifiers, options or whatever is applicable. Or something like a master-detail view for the entire data base, opening upon a selection the next detail view instead of a new column.

Such a tool would simplify the classification of new material, helps in finding required (yet missing) subitems, etc.

DoDi

This is the first problem: how much of the base class to repeat? Or how many links does the user have to follow to find what he seeks.

In PasDoc2 I imported inherited descriptions automatically, so that only really overridden behaviour must be documented, when it really does something different, or when it implements an abstract and unspecific method. This can also reveal in which class a method or property has been introduced, when the search starts in TDerived.ident and the help mentions TBase.ident.

DoDi

Well, The Lazarus book is nearing it's completion. It's meant for starters. Since it's in German, this will unfortunately be useful only for German speaking programmers...

Michael.

Zitat von Hans-Peter Diettrich :

The fpdoc help of the IDE (mouse hints) shows every fpdoc entry including all ancestor entries and all pasdoc comments, including all ancestor entries.
We have already a bug report from Graeme that this is too much.

Mattias

Thank you for your comments: I take them very much to heart. I have been trying to get through most of the LCL classes, to produce at least SOME documentation, and I agree that much of it is very simplistic, but yours is probably the first useful feedback I have had, in several years of work, and I thank you especially for this.

As Waldo Kitty said in the next post, 'maybe someone who understands geek but doesn't speak geek should be involved to "average joe" the documentation'. I thought perhaps I was that average joe, being a retired physician rather than a programmer.

Part of the problem is that several of the methods involved are overridden at every level of inheritance: your example of Notification is a good one, as every class that uses it overrides the ancestor, and usually calls inherited Notification as part of its code. By the time you get to the classes that actually appear as widgets on a Form, there may be up to five or six levels of inheritance, each of which has added an override to the original description of the method. How much should I reiterate the information present in all the ancestors? I thought that was one of the reasons we used links and 'seealso'.

My proposal is that I concentrate on classes that are most immediately apparent to the user/application programmer, the ones represented by symbols in the component palette (or their immediate parent CustomXXXXX classes), and produce as full a description as possible, along the lines you suggest, even if it involves re-iterating some of the material from more primitive levels. So I shall concentrate first on overridden methods in StdCtrls, ComCtrls and ExtCtrls.

Anyone with ideas for improvement is free to post a message, or even better, submit a patch for improved documentation.

Regards - Chris

It's too much, indeed. It IMO also shows that inline documentation (in the source code) is not very useful in class trees, where every derived class would either have no immediately visible comments, or would duplicate (possibly outdated) specs from the base classes - a maintenance nightmare :-(

For separate documentation a flag may be helpful, indicating whether the entry should replace or only extend the information, found in ancestor classes. A flag also could indicate the availability of information in ancestor classes, so that it's immediately obvious where missing information has to be added at all (newly introduced item), and where duplicate information should be omitted (inherited item).

DoDi

Anyone with ideas for improvement is free to post a message, or even better, submit a patch for improved documentation.

I found it very annoying that e.g. a TRect can effectively contain width/height *or* bottom/right in the BottomRight pair. Instead of adding according comments to all uses of TRect, I'd suggest to introduce new type names (not definitions!) for TRect, for use in all argument lists. Similarly for the different meaning of Client and Screen coordinates.

DoDi

Zitat von Hans-Peter Diettrich :

Where can TRect contain Width/Height?

Mattias

For a hint I agree. Even for a webpage, which is what I was talking about. hence the question: how much.

I gave an example, which had one phrase giving a very short description, of what is explained in greater detail on the inherited page.

Martin

I only starting looking at the help again when this thread came up. when I was new to lazarus (less than a year), I gave it a try, and I must have ended up a couple of times on docs that didn't help me (and back then I did probably not explore the "See also" link. I just thought: ok, new usable help, never mind.
That is why I pointed this out.

In fact before I send the mail, I had a draft, where I had nearly rewritten the base-help of Notification, before I discovered it. Once you know that, there is indeed a lot of help available.

I think it is not only he wording: "calls inherited" to me is useless, since it is no more than the pascal code reads. "calls inherited so inherited can do...." better. IMHO writing it in more natural language "passing the information/message/signal on to it's parent, so ..." makes it more readable.
( we were recently told that programmers are users too .... SCNR ;-> )

The essential is IMHO and as I said, to answer the first curiosity on the first page, which no need to click any link.it is the answer to a at least one of the question:
- Why is this called (in the example, why is the action list removed)
- When/Where is this called
In most cases at least one of the 2 (or both) should be present, even if it is just a short sentence. The details can be on a link (maybe the see also can be local attached to the sentence)

then of course the:
- What does it question.
This is already covered (in the example it already said, it removes the action-list).

True, that's why I gave an example. I didn't re-explain the full: it need to be registered by FreeNotification or to be owned.....

Notification can be used for a lot of different things, if a user wants to user it on it's own.
In the IDE it is used for a few different causes too.

The main one is that a child, or linked control is destroyed

There are 2 main reason why someone may have pressed help for it
1) they see it being used, and need to know what it does
2) They seek a function doing something, and need to find out if this is the one.

1) the first is answered (imho) by my example
" Called to notify the Form that another control has been destroyed (or otherwise removed). "
which is the main difference to the existing entry.

2) requires the full context from the base class and probably even examples. So it cannot be repeated in every class.

I agree with you it may be could to put some more info (maybe a copy) into the visible components T(Cutom)Form class. Those 2 should ideally have a combined help entry. Well for Notifiaction they will have that. For the properties, that are in TForm's published section, I do not know if it is possible.

Anyone with ideas for improvement is free to post a message, or even better, submit a patch for improved documentation.

I know...

Best Regards
Martin

2009/8/21 Martin :

I have to mention that fpdoc did not always contain support for base class documentation to filter through to descendants. A while back you had to document each class individually, even though one descends from another. This is not the case anymore, and the existing documentation needs to be updated to reflect this new behavior. Unfortunately this takes time and effort, so it's not a quick fix.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

i'm glad to see that you took martin's comments in a positive light... i hope mine were taken in the same or similar light...

As Waldo Kitty said in the next post, 'maybe someone who understands geek but doesn't speak geek should be involved to "average joe" the documentation'. I thought perhaps I was that average joe, being a retired physician rather than a programmer.

i meant no disrespect or harm when i wrote that... indeed, not knowing who all is/was working on all the documentation kinda hampers that... i had no way to tell if it was coders or not... i do applaud the work done and know that it is a hard job to do... i've done it myself numerous times over the years which is also why i started off with "fighting with myself" because i wanted to say something but didn't want to offend anyone or say something taken the wrong way...

you probably are the necessary "average joe" and, as you pointed out, it is taking time because of the sheer volume to be documented... if i knew more about Lazarus, the LCL and related items, i'd be more than happy to offer a hand... however, i'm still struggling with doing object coding instead of procedural coding and then doing it in a GUI environment as well... one of the first things is to learn the existing objects and routines, how they work and how to use them... without good easy to read and understand docs (local or online) it is hard to do... plus one has to have a project to work on as well :P

maybe i'll convert my card game from text mode TP6 to GUI Lazarus/FPC?? hummm...

speaking as a newcomer trying to learn Lazarus and FPC by using the available documentation, it is hard and confusing when you have to keep digging in deeper and deeper to fully understand what something does... then you have to back back out to where you were (if you can remember where you where when you branched) to travel down another path as well... and then another and another and another... my initial thinking on this is that possibly the highest level would contain info (briefly) on the deeper (inherited) aspects of the object along with a full description and working sample of its use like the built-in help in TP/BP... every entry for a built-in routine has a short working sample... as one walks deeper into the object's inheritance, they would loose only the higher layers of information and the current level would become the most detailed... yes, in each layer of the object would be links to the deeper portions...

that sounds like a good plan to me :)

Anyone with ideas for improvement is free to post a message, or even better, submit a patch for improved documentation.

i hope to be able, one day, to do more than stand over here on the sidelines trying to figure out how i can do more to help the project while at the same time being able to use the project for my own coding needs...

Maybe part of the problem is, that the person who writes the docs needs to already understand the code. But once you understand it, you look at documenting at a different level. That is because you knw the all the answer, you don't know which questions are out there.

In that respect (though I do not know how well this would work) part of improving the documentation would probably be that people without the answers (eg you waldo (no offense)) must ask them again. That is when you go to a help age you do so with a specific question in mind. if it isn't answered, then you can ask it.

The simplest would be to do so to the person who does the docs. but that wouldn't work, there would be do many questions. So you can go to the forum or the mailinglist. try to get the answer and then ask for it to be included. (even if it still needs rewriting)

The important thing is that you get a clear mind about what your question is.

It is NOT (or not only): What does this function do?

it is more likely:
- Why does this function do this?
- Why is this function needed?
- Where is it called?
- When is it called?
- What problem does it solve?
eg. Notification solves the problem of having an object pointer , that points to a destroyed object, and would cause an access violation, if accessed

Maybe the answer was given on a related page, but a short summary should be included?

Another set of question arises from the opposite search. You know what you need, but you do not know what it's named.

You may need a function that tests if a checkbox is greyed (neither checked nor unchecked)
That is how you came to vie the help for the "checked" property. But that doesn't tell you anything about your problem. What it needs is an explanation that a third state exists, and that there is a property called "state".

Of course not every cross-reference you may think as valuable can be included. But this help can be provided by everyone. Only you need first get the answer from the mailinglist, forum or google...

Btw I think the above link should be included. But the problem is that the propery belongs to a base class (TButtonControl) and that only some but not all descendands have the "State" property. and you don't want an entry on Tcheckbox.Checked, that only explains the difference to the base. if you press help for TCheckbox.checked you want one page with the current + the additional explanation.

So this needs some form of controlable inclusion of the base-help managed by the help system

Best Regards
Martin

Perhaps we should have an documentation tracker, where questions can be stored by everybody? The questions then can be linked to the existing or missing items in the overall documentation, and subsequent answers can become the base of the documentation to be added. Likewise links to existing (external) documentation or articles can be added to the links of the according help topics.

Useful documentation IMO is more a matter of organization or management, than of the goodwill to contribute to it. In so far it might be a good idea to open a new project, dedicated to the Lazarus documentation, with less restricted write access to everybody who has questions or answers. The related tools can be added to that project, again more open to the public than are the critical parts of the Lazarus project itself.

Such general questions should be reflected in the help system, for every topic. Different questions may apply to classes, methods, units, procedures etc. From an XML based view, the questions should reside in the structure part (XSD?), defining allowed and (optionally) mandatory parts (tags) of the entry data.

This is why I think that filling the overall help system with questions and answers should not be restricted in the same way as is the code in the SVN repository.

One of my ideas is a help level, where the user can ask for more or less information by increasing or decreasing the level (comes close to expanding or collapsing nodes in an treeview), or restrict the displayed information to specific sub-topics.

DoDi

Strange statement.

Because if no-one contributes, there is nothing to manage ?

Just like managers in a software company are secondary to programmers. If the programmers don't create, the managers can't sell. They cannot create, this is sure...

Any economist will tell you that production comes first. Economists don't often get it right, but in this case they did :-)

Michael.

Michael Van Canneyt wrote

Just like managers in a software company are secondary to programmers. If the programmers don't create, the managers can't sell. They cannot create, this is sure...

managers sell? i thought managers managed and salesdroids sell :P :lol:

There is such a thing as a Sales-Manager.
I meet it in the job advertisements every week :-)

I never understood what managing is anyway, but that is probably a flaw in my character...

Michael.