Documentation / tutorials need improvement (was: Object Pascal decline?)

[marcov]

What a nice article. marcov, do you know who's on the photo?

Me (right) and Mattias (left).

[marcov]

As for tooling, what do you use to write a book?  Latex is the classic answer, but something fpdoc or maybe docbook may be easier to generate webcontent. Latex focusses too much on transformation to print, and not enough on html.

Well, at least the wiki could actually be the publication of documentation.

Well, we could also publish it on animal hide. Possibilities does not equate something usable.

And I am really fond of having multiple formats and offline docs. Since I consider the wiki already a dump I don't care what else you dump in it, as long as it is not the only place, and there is an easy and compact offline solution.

I've been waiting for wiki exports of the lazarus help for 8 1/2 years now, so I do have some reasons to be critical of such schemes. Seems to be import first, fix problems later.

I.e. instead of generating pure "html" a tool could generate wiki markup and push documents to to the wiki. The page itself could be protected (so no free change would get into the page and a contributor would have to go through a mantis to update the documentation).

Docs use two tools:

fpdoc is mostly unit reference and exports to a host of files, with the popular choices latex or html (either online or for CHM). A backend here would be fairly easy, the trouble would be how to sync changes back to the original abstact formats that separate content from layout. As you would import layout information into the wiki.   fpdoc automatically updates function signatures etc.

The other manuals are direct latex, and these are run through a latex to html converter to generate HTML. If that is problematic it is fixed or mutated using homegrown fcl-xml tools.

That could keep the wiki as #1 source for information as well keep, it clean. at least on documentation part.

What does it really matter that it is in lazarus.freepascal.org/wiki/ref.html instead of lazarus.freepascal.org/docs/ref.html ? You can have wiki portals refer to the main site too.

[marcov]

Btw, Michael's  reactions in the "lexical diagrams" thread in fpc-pascal sums it up nicely:

Wikimedia is NOT documentation. It is a knowledgebase.

[ArtLogi]

So the solution is?

[marcov]

So the solution is?

Write docs, don't obsess about tools. Cherry pick the wiki for the rare nuggets that might appear there, but don't rely on it. Integrate that info into the mainstream docs.

Cooperate, and adapt to people already writing docs instead of rolling out a parallel vision, tooling and solution. Assume your vision is wrong till you at least have a level of proficiency with the current tools.

Revolution can be healthy sometimes, but all too often it is chasing windmills. Fragmentation is the worst enemy.

[skalogryz]

Me (right) and Mattias (left).

Hmm, Physiognomy is real. You and John Carmack look like brothers!

[skalogryz]

Fragmentation is the worst enemy.

Yep. And it's already happening, even within the same community! (assuming FPC+Lazarus community)
RTL on Lazarus-CCR
Official FPC RTL
(browsing through documentation, one might note that CCR version is dramatically outdated. Though some wiki articles are referring to CCR pages)

[skalogryz]

I've just noted! Delphi's documentation is supplied via wiki.

[Graeme]

@skalogryz
And if you have been listening to any developer using any Delphi XE and later version, they all tell you how much the documentation sucks (compared to say Delphi 7).

One notable difference between Delphi's wiki and Lazarus's wiki. The Delphi wiki has documentation per release. Lazarus documentation is a constant moving target, so the wiki is useless for older Lazarus releases.

The other point is that Delphi also ship with [crap] offline documentation. Lazarus only ships with RTL, FCL and LCL help, no IDE help, no tutorials, quick start guide etc.

[skalogryz]

And if you have been listening to any developer using any Delphi XE and later version, they all tell you how much the documentation sucks (compared to say Delphi 7).

I doubt that. It's either Delphi 7 documentation sucked as much as the current version or they are just talking about user experience of the documentation (rather than it's contents).

One notable difference between Delphi's wiki and Lazarus's wiki. The Delphi wiki has documentation per release.

Hm.. delphi versions seems like separate wikis. (physically different wiki database). That means that edits to one version are not propagated to other versions. Doesn't look good at all.

Lazarus documentation is a constant moving target, so the wiki is useless for older Lazarus releases.

Well, in most cases, when an edit occurs, the information about previous release remains, rather than being deleted.

...no IDE help, no tutorials, quick start guide etc.

Offline IDE help? Interesting.

[Graeme]

... or they are just talking about user experience of the documentation (rather than it's contents).

It was both actually. Lots of content was missing or outdated. The HxS (or whatever that microsoft help format is called) was extremely buggy and very very slow. Most times pressing F1 while coding did not result in any help found.

It was so bad and had so many complaints that Embarcadero was pretty much forced to move back to CHM help in Delphi XE8 onwards.

...no IDE help, no tutorials, quick start guide etc.

Offline IDE help? Interesting.

Yes, it is something every end-user or developer should insist on, for any software. If I sit in business class on a 16 hour long haul flight and I need to get work done (without internet access at 30,000 feet), I would like to be able to press F1 and get context sensitive help, or browse a tutorial on how to use a complex component, or get an explanation of the meaning of a dialog etc. If everything is always online only help, I'm sh*t out of luck.

[marcov]

Yep. And it's already happening, even within the same community! (assuming FPC+Lazarus community)

Yes. Because new people fall for the old trap again and again, talk about principles ad infinitum, and generate very few content that is merged back into general efforts. So if the person gives up it dies.

I've just noted! Delphi's documentation is supplied via wiki.

And a very typical one. Import in a wiki for show and to appear social, zero contributions, and probably no link with the actual repository for documentation development.

I doubt that. It's either Delphi 7 documentation sucked as much as the current version or they are just talking about user experience of the documentation (rather than it's contents).

I liked the D7 docs too. The language guide could be used as tutorial, nicely in order, every chapter building on the previous ones.  And I care about usability and content mainly.

One notable difference between Delphi's wiki and Lazarus's wiki. The Delphi wiki has documentation per release.

Hm.. delphi versions seems like separate wikis. (physically different wiki database). That means that edits to one version are not propagated to other versions. Doesn't look good at all.

I think they mainly use the wiki as a kind of online CMS to be able to do changes after the initial release, but I don't think the wiki is part of the actual documentation process. You don't see author edits. (if you see edits at all). This means that changes have to be done multiple times (real documentation repositories and wiki per version)

Note that Embardero does provide everything in offline help! So actually Embacadero doesn't use wiki as central doc repo, nor as only solution.

Lazarus documentation is a constant moving target, so the wiki is useless for older Lazarus releases.

Well, in most cases, when an edit occurs, the information about previous release remains, rather than being deleted.

Not my experience. Some of the worst gotchas get a special mention, but the bulk is overwritten. Not really a wiki problem though. If you have multiple versioned other repositories, the risk of having to do fixes multiple times remains.

I don't consider that such a problem, since I can't see such detail work happening anything soon. As far as versioning goes, I only want to be able to see the content that was specific to a release, it continously being updated for multiple versions is currently a bridge too far.

[valdir.marcos]

Write docs, don't obsess about tools. Cherry pick the wiki for the rare nuggets that might appear there, but don't rely on it. Integrate that info into the mainstream docs.

Cooperate, and adapt to people already writing docs instead of rolling out a parallel vision, tooling and solution. Assume your vision is wrong till you at least have a level of proficiency with the current tools.

Revolution can be healthy sometimes, but all too often it is chasing windmills. Fragmentation is the worst enemy.

Because new people fall for the old trap again and again, talk about principles ad infinitum, and generate very few content that is merged back into general efforts. So if the person gives up it dies.

I liked the D7 docs too. The language guide could be used as tutorial, nicely in order, every chapter building on the previous ones.  And I care about usability and content mainly.

I think they (Idera/Embarcadero] mainly use the wiki as a kind of online CMS to be able to do changes after the initial release, but I don't think the wiki is part of the actual documentation process. You don't see author edits. (if you see edits at all). This means that changes have to be done multiple times (real documentation repositories and wiki per version)

Note that Embardero does provide everything in offline help! So actually Embacadero doesn't use wiki as central doc repo, nor as only solution.

Not my experience. Some of the worst gotchas get a special mention, but the bulk is overwritten. Not really a wiki problem though. If you have multiple versioned other repositories, the risk of having to do fixes multiple times remains.

I don't consider that such a problem, since I can't see such detail work happening anything soon. As far as versioning goes, I only want to be able to see the content that was specific to a release, it continously being updated for multiple versions is currently a bridge too far.

What about creating a documentation team and centralizing everything such as Idera/Embarcadero Delphi, but in a better collaborative way?

Just an example: Firebird-docs is a volunteer team inside Firebird that is responsible for its documentation aided by everybody including core developers providing information and solving doubts. Most of the document writers are not core programmers:
http://www.firebirdsql.org/file/documentation/release_notes/html/rlsnotes255.html#rnfb25-fb2teams
http://www.firebirdsql.org/manual/docwritehowto.html
http://www.mail-archive.com/firebird-docs@lists.sourceforge.net/
http://www.firebirdsql.org/en/documentation/

I know that FPC + Lazarus lack of manpower and those with knowledge should be writing documentation locally in textformat and submiting patches via some version control system (such as SVN, GIT, etc), in good open source tradition.

We could organize and divide the work in subteams, for example:
- who has some or much knowledge write the docs (in latex or docbook?);
- another team revise and organize those docs and create books for specific versions of FPC or Lazarus;
- patches would be managed via Mantis Bug tracking system;
----------------

For version FPC 2.6.x, there are already some books:
----------------
This is the user’s guide for Free Pascal:
ftp://ftp.freepascal.org/fpc/docs-pdf/user.pdf
This document serves as the reference for the Pascal langauge as implemented by the Free Pascal compiler:
ftp://ftp.freepascal.org/fpc/docs-pdf/ref.pdf
This is the programmer’s manual for Free Pascal:
ftp://ftp.freepascal.org/fpc/docs-pdf/prog.pdf
This document describes all constants, types, variables, functions and procedures as they are declared in the units that come standard with the FCL (Free Component Library):
ftp://ftp.freepascal.org/fpc/docs-pdf/fcl.pdf
This document describes all constants, types, variables, functions and procedures as they are declared in the units that come standard with the Free Pascal Run-Time library (RTL):
ftp://ftp.freepascal.org/fpc/docs-pdf/rtl.pdf
FPDoc: Free Pascal code documenter: Reference manual:
ftp://ftp.freepascal.org/fpc/docs-pdf/fpdoc.pdf
----------------

We could - in a collaborative way - update and/or create new books:
----------------
-- Free Pascal 3.x - Beginner's Guide
-- Free Pascal 3.x - Language Guide
-- Free Pascal 3.x - FCL - Free Component Library
-- Free Pascal 3.x - RTL - Run-Time Library
-- Free Pascal 3.x - FPDoc - Free Pascal code documenter
----------------
-- Lazarus 1.6.x - Beginner's Guide
-- Lazarus 1.6.x - IDE - Integrated Documentation Editor
-- Lazarus 1.6.x - RAD - Rapid Development Application
-- Lazarus 1.6.x - OOP - Object Oriented Programming
-- Lazarus 1.6.x - LCL - Lazarus Component Library
----------------

- offline help could be created from latex/docbook to chm/inf/pdf/html in a similar way to what existed in Delphi 7;
- video tutorials would only be created for very specific topics;

- wiki would stay just as a knowledge base for extra subjects or tips or tweaks not included in the "oficial manuals";
- everything that was created via textformat (latex/docbook) could be exported to online (pdf/html);
- at the end, we could even have volunteers to translate the content in textformat to generate offline and online documentation in others languages than English.

[marcov]

What about creating a documentation team and centralizing everything such as Idera/Embarcadero Delphi, but in a better collaborative way?

It is already centralized, and people that work on the docs (and show that by having contributed significant patches) get access.  Just like e.g. Lacak got write access to all things db related,

I know that FPC + Lazarus lack of manpower and those with knowledge should be writing documentation locally in textformat and submiting patches via some version control system (such as SVN, GIT, etc), in good open source tradition.

You don't need much latex knowledge to modify the plain textfiles. Even things like screenshots is just copying the standard line to include a picture, and change the filename. (+/-)

You could deliver a complete tutorial book in msword if you are happy with that, and I'll gladly do the latex conversion. Those are all non-existing hurdles.

The problem is that nobody does anything (*) except suggesting different policies and tools.

 (*) a few exceptions that submit mostly minor corrections like Graeme.

[valdir.marcos]

It is already centralized, and people that work on the docs (and show that by having contributed significant patches) get access.  Just like e.g. Lacak got write access to all things db related,

You don't need much latex knowledge to modify the plain textfiles. Even things like screenshots is just copying the standard line to include a picture, and change the filename. (+/-)

You could deliver a complete tutorial book in msword if you are happy with that, and I'll gladly do the latex conversion. Those are all non-existing hurdles.

The problem is that nobody does anything (*) except suggesting different policies and tools.

 (*) a few exceptions that submit mostly minor corrections like Graeme.

You are right.

All this documentation thread discussion is useless. Nothing needs to be changed.

Fragmentation is not happening and initiatives such as http://www.getlazarus.org/learn/language/ means that everything is working all right.