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

[marcov]

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).

I know that. I own and read the wiki-way book. I'm however talking about the practice I see on the web (documentation in the wiki, often with limited write access). The suggestion here goes even further essentially going world writeable. And the too many cooks spoil the broth principle.

And if you really want to go the wiki way, you will need people massively investing in creating wiki management technology. I don't see that happening.

And one could also write on the back of bark, and than scan that in. Something theoretically possible is not directly a good thing.

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

Head is the front page, tail is the back page.  In short an ordinary book, with chapters, and the assumption that what's needed in knowledge in chapter 10 has been explained before chapter then.

I mean this in opposition of the more loosely connected lemma based wiki (and help!) principle. In short, I think the change in Delphi, going from the old manuals to the current situation was not good either. Call me old fashioned.

And that is doubly so for people that have to start from nothing (read: newbies that really want/need to get up to speed).

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.

The core reasons for such products (instead of e.g. word) is SVNAbility of course, fragmentation over multiple files (a concession to get at least multiple (though not infinite) authors getting things done in parallel)

The point is that I don't believe in  gathering docs in a massively colaborative way. The few places where that happens is more despite the world writeablity than thanks to it, and usually there is a hard core (and often paid) group that does most of the work. I hear wikipedia is up to 300 now.

So just write a doc to an outline with first things first, instead of lemma based hyperlinked mess.

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.

Well, there have been some minor ones, e.g. in "size matters", and IMHO too many articles have alternate fpgui and msegui paragraphs. But the impact is still minor.

Unfortunately, the non sequential and low quality issues are very visible. I write the current wiki off as the "misc" bin of documentation, not belonging to the documentation

[sysrpl]

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

I hope when I am further along with my wiki docs you'll have a change of heart:

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

My wiki engine, which I build from scratch, prevents vandalism. I have a back end page which shows me the diffs across all pages and the IP addresses associated with them. Individuals can see their own edits, but I can easily review all diffs before approving or altering their merging, or simply delete/block/ignore other people's bad edits.

Also note, the wiki uses a tree hierarchy for pages with a breadcrumb navigation bar atop.

Currently I am writing a javascript canvas renderer to convert special markdown into lexical syntax diagrams.

[ArtLogi]

Hey systemreversepolishlisp, I edited that last program example adding a line:

Code: Pascal  [Select][+][-]

1. ReadLn; {This line is not necessary, but prevents CMD-window to close until user press Enter in some MS Windows systems}

The wording in the comment is rather long though. I though the case where someone tries to run the .exe from windows explorer.

[marcov]

I hope when I am further along with my wiki docs you'll have a change of heart:

IMHO the classical mistake of focussing on tools instead of content. (fix the tools and the content will come) This is fundamentally flawed reasoning. If not, the current wiki would have had perfect docs since it is in existence for over 10 years.

So I doubt it will change anything but visual makeup.

[skalogryz]

I know that. I own and read the wiki-way book. I'm however talking about the practice I see on the web (documentation in the wiki, often with limited write access). The suggestion here goes even further essentially going world writeable. And the too many cooks spoil the broth principle.
....
The point is that I don't believe in  gathering docs in a massively colaborative way. The few places where that happens is more despite the world writeablity than thanks to it, and usually there is a hard core (and often paid) group that does most of the work. I hear wikipedia is up to 300 now.

I still believe that collaborative writing could work. And it could work the same way as open source projects (with no/limited write access) are working.  The same approach - reviews and editorials.
An edit could be corrected toward the documentation rules (which wiki-sites impose, this way or another).

The point of world writeability is to gather the information (views / ideas). Eventually someone would have to organize it.

Head is the front page, tail is the back page.  In short an ordinary book, with chapters, and the assumption that what's needed in knowledge in chapter 10 has been explained before chapter then.

I mean this in opposition of the more loosely connected lemma based wiki (and help!) principle. In short, I think the change in Delphi, going from the old manuals to the current situation was not good either. Call me old fashioned.

it's not about the wiki itself, it's more about contents.
Wiki is more a library, rather than a single (huge) document. (That's why it bears documents organizing tools, such as categorizing)

Here's an example of a book on freepascal wiki. I could agree, that visually it looks a bit weird for the wiki itself, but it's or a technical problem (which could be resolved, via plugins or something)

Note: thanks to the wiki (as a tool), the book also got translated to several languages.

[skalogryz]

Here's an example of a book on freepascal wiki. I could agree, that visually it looks a bit weird for the wiki itself, but it's or a technical problem (which could be resolved, via plugins or something)

Note: thanks to the wiki (as a tool), the book also got translated to several languages.

*sigh* technically (from wiki point of you) it has been terribly implemented
But this is the place, where wiki editors should jump in!

[marcov]

I still believe that collaborative writing could work.

Oh sure, it could work maybe. But is it the most efficient way in practice? I doubt it, since it forces people that are active in the document department (and those are scarce) to overly spend type on organizing and cleaning up the mess of all kinds of wellmeaning but inexperienced authors (and then I'm kind enough to forget actual abuse).

And it could work the same way as open source projects (with no/limited write access) are working.  The same approach - reviews and editorials.

A very select group has write access on such systems. That is actually what is the killer, and the problem is there that the benefits of doing it online start to outweigh even the potential benefits.

There have been discussions before, the best way would have some online authoring system where users can suggest or annotate things, and that is fairly abstract so that it is somewhat machine processable.  (for other format generation, mutation information for translators etc)

One could put a versioning system under the CMS/wiki system even.

But I think a plain mediawiki is simply too simple for that, and I rather have people write docs now then start a very long trajectory on developing tools. Trouble is that too many people want to write tools to maintain docs, and too few want to write docs ;-)

An edit could be corrected toward the documentation rules (which wiki-sites impose, this way or another).

True, but all this is overhead. And there have been experiments before (importing docs into a wiki with an annotation system for the next version), but the examples are underwelming.

As soon as it takes a bit of effort, and people can't edit and see it directly online, submissions drop.

Don't take such effort, and you are forever mired with heaps of very low quality edits, and the effort to actually make something out of them is larger than the value of the input itself.

The point of world writeability is to gather the information (views / ideas). Eventually someone would have to organize it.

That was the whole idea of the annotated docs too, yes. And admitted that experiment was not ideal either (there were no fixed points to link the imported docs  to the next version of the imported docs).

An annotation system would work, and might be a fun job for sb interested in these kind of websystems. But all people only want to replace all existing processes with a wikipedia approach, and that is IMHO madness.

You example illustrates my point perfectly. What you see is what is there, and note that is an import of an external document into the wiki. And a bad import even.

That content is not created in the wiki (and it is the only content with an order, which says enough in itself). There is no way to compare mutations after import with the original document, no two way street. Only import and then let the forces of chaos loose on it.

[ArtLogi]

Here's an example of a book on freepascal wiki. I could agree, that visually it looks a bit weird for the wiki itself, but it's or a technical problem (which could be resolved, via plugins or something)

Note: thanks to the wiki (as a tool), the book also got translated to several languages.

*sigh* technically (from wiki point of you) it has been terribly implemented
But this is the place, where wiki editors should jump in!

That is indeed nice starter book and had a few usefull chapters what I did read it (jumping between old TP and Delphi books, google, wiki and forums here), but for my eyes that book have one limitation as it does have this hybrid license, it is not truely a opensource write up. Ie. if you add a new chapter to it how you should handle the license etc. it brings these oddities to contributors. It would be much more straightforward to have real CC licenced (or what the wikipedia is using) book, where you don't need to think how to take the license to account when expanding the content.

@Marcov It does have the "History" tab for tracking down the changes:
http://wiki.freepascal.org/index.php?title=Hello%2C_World&action=historysubmit&diff=91252&oldid=25310

PS. I think the biggest drawback of MediaWiki engine is that it is loosely structured(.. not loosely structured, but doesn't have really good tools for tree type of hierarchical visualisation between pages, only extensions provide something like that) what comes to categories etc. It is encyclopedia (a word book) engine after all.

[skalogryz]

I still believe that collaborative writing could work.

Oh sure, it could work maybe. But is it the most efficient way in practice? I doubt it, since it forces people that are active in the document department (and those are scarce) to overly spend type on organizing and cleaning up the mess of all kinds of wellmeaning but inexperienced authors (and then I'm kind enough to forget actual abuse).

I'd think yes - it would work. And it would work because of human psychology and being able to follow rules.

First, there has to be a set of rules created on how an article should be like. There were an attempt to enforce that, but since rules were not written anywhere (?), nobody is following them.
Second, any contributor should be aware of these rules (be able to read them, and follow them)
Thirdly, any contributor has a write to correct any edit to make follow the rules. That should relieve the burden  of "low-level" corrections from the "document department".  Some sort of self-healing system.

At least wiki technically allows it.

But I think a plain mediawiki is simply too simple for that, and I rather have people write docs now then start a very long trajectory on developing tools.

Well.. despite of annotations should be done as edits on the wiki (or at least as commit on discussion pages). It has all the required features:
* Edits are authored and time stamped.
* Versioning is available. actually no! It's not just a history of the document.

...you are forever mired with heaps of very low quality edits, and the effort to actually make something out of them is larger than the value of the input itself.
...
Trouble is that too many people want to write tools to maintain docs, and too few want to write docs ;-)

That actually saves the whole idea of world world writeability. The number of commits would be low. Just by the fact writing is a very hard job to do!  (obviously much harder, than writing code)
So the number of low-quality commits is expected to be even lower.

That was the whole idea of the annotated docs too, yes. And admitted that experiment was not ideal either (there were no fixed points to link the imported docs  to the next version of the imported docs).

An annotation system would work, and might be a fun job for sb interested in these kind of websystems. But all people only want to replace all existing processes with a wikipedia approach, and that is IMHO madness.

You example illustrates my point perfectly. What you see is what is there, and note that is an import of an external document into the wiki. And a bad import even.

That content is not created in the wiki (and it is the only content with an order, which says enough in itself). There is no way to compare mutations after import with the original document, no two way street. Only import and then let the forces of chaos loose on it.

Hmm... versioning ... branching

[skalogryz]

PS. I think the biggest drawback of MediaWiki engine is that it is loosely structured(.. not loosely structured, but doesn't have really good tools for tree type of hierarchical visualisation between pages, only extensions provide something like that) what comes to categories etc.

It actually does even without extra plugins.
Just by the fact it allows a plain html to be inserted into the page. But the piece of html into a wiki template, and you can easily have it on the every page of the book.

The actual problem here, is that book itself takes over the global space of page names. For example, the book has several "Solution" sections in its chapters. In order to make each section a stand-alone page, it has been given a unique name: Solution, Solution_1, Solution_2 etc... That's kind of a waste here. Needless to say, searching for "Solution" would bring a user to the book.  Which is not expected!

What should have happened, is pages were to created as subsections of the book and named accordingly: "Object Pascal Tutorial/Chapter 1/Solution", "Object Pascal Tutorial/Chapter 2/ Solution" and so on.

In this case the global name would stay clean.

... in general, since sections are quite small, it would be better to have a chapter per wiki page, rather than a section per page.

[marcov]

I'd think yes - it would work. And it would work because of human psychology and being able to follow rules.

First, there has to be a set of rules created on how an article should be like. There were an attempt to enforce that, but since rules were not written anywhere (?), nobody is following them.

Nobody would look at the rules till they get something to block their way (read: rules are enforced) Why? Human psychology again. People go for the simple case (just edit) till something prohibits that. Evolution driven efficiency, first try "good enough".

If not, people would always search the forum and look at faqs before posting.

Second, any contributor should be aware of these rules (be able to read them, and follow them)
Thirdly, any contributor has a write to correct any edit to make follow the rules. That should relieve the burden  of "low-level" corrections from the "document department".  Some sort of self-healing system.

But that is roughly the same as the committer system. Basically then you are talking about an web-based revision system instead of a laissez faire wiki approach.

But I think a plain mediawiki is simply too simple for that, and I rather have people write docs now then start a very long trajectory on developing tools.

Well.. despite of annotations should be done as edits on the wiki (or at least as commit on discussion pages). It has all the required features:
* Edits are authored and time stamped.
* Versioning is available. actually no! It's not just a history of the document.

So why is the wiki such a mess after 10 years?  Where has that magic self organizing element been all those years?

That actually saves the whole idea of world world writeability. The number of commits would be low. Just by the fact writing is a very hard job to do!  (obviously much harder, than writing code)
So the number of low-quality commits is expected to be even lower.

Yes, but the volume is still large compared to the people that know what they are doing. And they are not working on the docs but maintaining the mediawiki infrastructure and fixing other peoples mistakes.

Hmm... versioning ... branching

So how are you practical experiences with branching in a mediawiki environment? Does it work like SVN or like GIT ?

[skalogryz]

Nobody would look at the rules till they get something to block their way (read: rules are enforced) Why? Human psychology again. People go for the simple case (just edit) till something prohibits that. Evolution driven efficiency, first try "good enough".

If not, people would always search the forum and look at faqs before posting.

I've no solution for that, except for bunch of angry moderators to punish people

But that is roughly the same as the committer system. Basically then you are talking about an web-based revision system instead of a laissez faire wiki approach.

But this is how wiki works (in theory). I would never say that wiki is laissez faire approach. Wikipedia has the strict hierarchy of moderation, yet still allowing free form edits.

Some of long-term community participants are sort of doing the moderation job. Though I'd say people are being too polite to others work, and maybe they should be strict.  But since there're not written rules to back them up, they don't act as mighty as they could.
Me personally are going to do some clean ups in iOS section of the wiki (eta: this weekend).

So why is the wiki such a mess after 10 years?  Where has that magic self organizing element been all those years?

The same reason why FPC and Lazarus are mess (lack of manpower).
Magic is there, acting slowly. For example: pages are being categorized , people are creating portals and binding pages together.

So how are you practical experiences with branching in a mediawiki environment? Does it work like SVN or like GIT ?

None I never looked for mediawiki branching before

[marcov]

Nobody would look at the rules till they get something to block their way (read: rules are enforced) Why? Human psychology again. People go for the simple case (just edit) till something prohibits that. Evolution driven efficiency, first try "good enough".

If not, people would always search the forum and look at faqs before posting.

I've no solution for that, except for bunch of angry moderators to punish people

Those capable of moderating should be writing docs.

But this is how wiki works (in theory). I would never say that wiki is laissez faire approach. Wikipedia has the strict hierarchy of moderation, yet still allowing free form edits.

No, that is how wikipedia "works"  (opinions vary, in most countries people in education are not even allowed to cite wikipedia). The wiki book mostly treats in organization (e.g. knowledgebases).

Massive online get my docs for free is not original wiki theory, but WEB2.0 hype.

Some of long-term community participants are sort of doing the moderation job.

Sure. But the problem with moderation is that you can only kill excesses. Which is why there are KOL, FPGUI and MSEGUI sections in half of the Lazarus articles. And worse, those people should actually be writing docs, not cleaning them.

Though I'd say people are being too polite to others work, and maybe they should be strict.  But since there're not written rules to back them up, they don't act as mighty as they could.
Me personally are going to do some clean ups in iOS section of the wiki (eta: this weekend).

Yes, moderators are just more active, they have no authority at all. But even if they had authority, that only allows them to correct the worst stuff, not keep it at the gate as not good enough.

Probably using the wiki for docs is the greatest inhibitor to having proper docs. People can just dump whatever they want to write, on every place where they want to write, and there is no correction mechanism at first. 

There is no system as with e.g. code where patches are iterated etc.

The same reason why FPC and Lazarus are mess (lack of manpower).

I think the state of FPC and Lazarus is a lot better than their docs.

Magic is there, acting slowly. For example: pages are being categorized , people are creating portals and binding pages together.

I know, but I think much of that is also fairly low value.

So how are you practical experiences with branching in a mediawiki environment? Does it work like SVN or like GIT ?

None I never looked for mediawiki branching before

Exactly. It is all theory, and it is hard to come up with a example of a project with our resources (read: not wikipedia, and even that is doubtful) that works. Contrary to SVN, Mantis and the rest of the resources we use.

I'm not anti-wiki per se, but IMHO in the current form it is not conductive to generating any form of quality content (and... available offline and linked with the IDE).  I think it would be good to make the wiki the "misc" bin for fastmoving info instead of the default location again.

[skalogryz]

Sure. But the problem with moderation is that you can only kill excesses. Which is why there are KOL, FPGUI and MSEGUI sections in half of the Lazarus articles.

If a page is a general/overview page, (i.e. packages) then mentioning different versions would be appropriate. Naturally, the more detailed information could be given on the specific page (i.e. FPC packages / Lazarus packages / MSEGUI packages, etc.)
I'd think this is not happening, yet again because no rules are defined, but rather assumed. If a "moderator" sees the violation of content, would he/she act on assumption to clean it?

Those capable of moderating should be writing docs.
..
And worse, those people should actually be writing docs, not cleaning them

Authors of components are typically writing docs.
Here're two examples CudaText and RichMemo. The main articles are written by components authors. Other components maintainers are also trying to update the wiki. For example, "Release notes" pages for both FPC and Lazarus are updated carefully by core members.

People can just dump whatever they want to write, on every place where they want to write, and there is no correction mechanism at first. 
There is no system as with e.g. code where patches are iterated etc.

That actually reminds me, that some times, I can see corrections coming in very fast on any new change made.
Though it might be happening, because the recent change draw's moderator's attention.
I can only say, that just like code, there's some process of review, but it's happening after the fact of the change.

[skalogryz]

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. 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).

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

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