At 11:03 PM +0100 30/1/03, Frank Heckenbach wrote:
Grant Jacobs wrote:
What I'm suggesting is a little different. Provide a framework within the docs that users can add their own observations to, but one that such that readers can see that its a user contribution. Then users can add as little or much as they like.
You'd occasionally want an editor to run over the whole thing and make it more consistent. (Or have two versions of the docs - last edited version and the free-for-all version)
In the end, it really comes down to the fact that someone has to write the stuff ...
Actually, it's not a big issue for me to apply documentation changes I get (and to review them for serious mistakes) -- a simple patch sent to me or the gpc-doc list will do. I've been getting some up to now -- but unfortunately too sporadic and by far not enough to really cover the holes ...
If you can get the automatic docs out in some format, have a field 'user notes' or whatever present. Let the users add to that. You can then receive contrib.s as diffs or simply merge the new and old docs.
OK, I think I can do that -- to add an input form at the bottom of each page, so anything entered there will appear on the page (just above the input form I guess) marked as user notes, and is sent to me so I can put it into the main documentation if it's alright. Is that what you mean?
I was thinking more of a field like the ones already there. E.g. You have for each item synopsis, description ... see also.
I was thinking after 'see also' add 'User's observations' (or some-such)
This way their observations are tied to each element, rather the bottom of each page. Let that field be added to by users as they see fit. Periodically spring-clean shifting bits that look OK to the main ("certified" :-) ) part of the docs.
Its a little awkward, but ideally you'd have a section like this after every section in the docs. You could filter the docs so that empty User observation sections are stripped (outside the appendix listings of the keywords, that is; these probably should have a fixed format as they do now so its easier for a reader to spot missing stuff) before making the PDFs, etc.
So, say I want to add some of my own observations to '3.4.6 What about C strings', I can submit/add to a 3.4.6U (of sorts), which will appear under 'User observations' (or whatever) in that section. Later these can be integrated if they are deemed OK, or possibly junked if they can be contradicted.
Would this be too difficult? Or am I too confusing :-)
I'm still skeptical how much it will gain us in the end, but since there's not much to lose, I'll try it (with the next update) ...
You gotta try!! If there is an easy route for people to add their bits they are more likely to do it - we hope...
Grant