Okay, a proposed solution.
It is a living document, with snapshots taken and released from time to time.
The document is developed on a dedicated forum or a wiki. Let us say a forum.
The forum is divided into document groups.
Each doc group has a topic for the section, and the first few posts in that section are the reserved for the actual doc.
All other posts are suggestions, ideas, questions on the section.
The groups/documents are:
Tutorial
This is a basic intro to programming concepts and targets newcomers to programming and very old hands who last coded when the abacus was
the machine and who now have to learn new tricks like OOP, events, etc.
So it would explain variables, etc, and events, and etc.
Manual
The manual is the guts of the doc, and goes into detail about things. This is where things like
*ptr and
ptr being different variables is explained, and the actual differences in how PB deals with a *var versus a var (if it does so) are explained.
The manual is organised along logical groupings - the basic folder structure of the code archive from
www.purearea.net is a good example of this grouping. Perhaps it should be used as the structural template for the manual, as it is, well, logically organised.
Reference
The reference section is similar to the current help and manual, but the groupings are dropped and things are in alphabetical order.
Each entry has it's own example, even if this is a duplication of the example used for associated code. It has a reference link to the more detailed manual, and "see also" links.
Appendices
Lists of things like PB constants
OS significant things
- - - - - - - - - - -
The documents outlined above will take a lot of work. But it can be done quickly.
Firstly, the "document posts" are authored by a team, each having access to edit those posts. These "posts" are set up when the forum is created and in the initial stage they will merely be *RESERVED*.
Posts following the document posts are suggestions, queries, ideas, etc, by interested parties.
Everyone can help. Grammer, spelling, ideas on how to explain concepts, etc, are posted here. Posts by newbies and slowbies and dare2s will bring out the confusing parts of the documentation. Comments by experts will ensure the code and tech detail is well explained.
The "team" can adjust the "document posts".
The project is overseen by the Fred and his PureBasic team.
Authors are volunteers good at explaining things, not necessarily good coders or PB experts, just so long as they can understand the concepts and explanations of the gurus, and explain them to the tyros.
Everyone who wants to can go to the board and read, and make comments.
- - - - - - - - - - -
Snapshots are taken from time to time. The "document posts" are extracted and html created.
This html is can then turned into .chm, or .pdf, or .doc, or .whatever.
The document becomes a part of the download.
It also becomes the online docs for PB.
And it is downloadable as a sep file in the supported formats.
When the snapshot is taken, all posts are cleared from the forum, save the "doc" posts, and the "living" document lives on until the next snapshop. And then lives on.
- - - - - - - - - - -
Once started, the benefits are there for everyone. For PB because the documentation is an important part of the product.
For participants and volunteers because as they help, they learn and become gurus themselves. They become good. Having to explain something clarifies the mind and improves understanding.
This in turn lifts the core expertise of the PB user base.
- - - - - - - - - - -
Notes:
It is PB documentation, not 3rd party user library documentation.
It does not cover user libraries. (Bet many of you are so used to these libraries that you've forgotten you use and depend on them - and the newcomer wonders why things don't work)
It is not win or linux or AmigaOS documentation BUT there should be sections for OS significant stuff.
The first posts per thread/topic are used as:
1. "Current Final" or best so far documentation.
2. Directives to document building scripts as to where to cross reference, etc.
3. Working draft, cut and pasted to (1) "Final" from time to time.
4 onwards. User contributions and ideas.
- - - - - - - - - - -
I run something like this on some intranets (which have nothing to do with programming but do have process and application of process requirements).
Simple scripts do the snapshots, creating chapters, sections and indexes, clear posts, etc, on demand.
The people in the intranets using the approach are all more clued up and effective than those where the intranet managers decided against the approach. Newcomers have good official docs, and can visit the living doc to get up to date info. And post their confusions, to the benefit of the next doc release.
I believe it would work here.
The bulk work is the setup. Thereafter all you have is modification (sometimes major, mostly minor) and steadily improving documentation.
We need a forum, pref by PB. If not possible to provide by PB/FS, then I will provide one on one of my sites. But pref PureBasic does - and uses their bandwidth
Fred and team also need to decide on who the official authors are. Again, good explanation is better than good coding.
Finally - the project is egoless and without hierarchy, save for Fred and PB team overseeing the thing.
Everyone makes good use of their talents. Advising on grammer is as important as advising on code. Nobody needs to prove how good they are, the only success is if the doc does what it should - teach and help people.
but i have seen it done where i used to work.
)