[gambit-list] Adding docs to wiki?
Jonathan Arkell
jonnay at jonnay.net
Mon Dec 1 23:26:12 EST 2008
On 1-Dec-08, at 11:46 AM, Marc Feeley wrote:
>
> I'd like to get some feedback on these pages before I put the rest of
> the Gambit manual on the wiki. Some issues:
>
> 1) What name should the pages have? I use the Procedure_ and
> Special_form_ prefixes so that a name can easily be found. But
> perhaps it is better to have a unique prefix (Documentation_of_ or
> simply nothing, but this might cause a name clash) so that the page
> can be accessed directly without knowing if the name refers to a
> procedure or a special form. This would make the wiki documentation
> easy to access from an IDE. I can easily imagine the IDE adding to
> the error messages a hyperlink to the wiki documentation of the
> procedure which raised the exception.
I like Special_form and Procedure_ prefixes. You might need some
other prefixes as well. If you categorize all the documentation
pages, you can automagickally have indexes and tables of contents
built up with mediawiki.
> 2) Where should the documentation which is outside the Texinfo @deffn
> forms be put? For example, general discussion of I/O, or debugging,
> or the compiler, general index, concept index, etc.
Why not Documentation_of_debugging, and Documentation_of_I/O?
Again, the General Index and Concept Indexes should be handled via
categories.
> 3) How should hyperlinks work within the wiki?
I am not sure I understand this question. Why not handle them as
wiki links?
> 4) Can the HTML's prettiness be improved?
Yes. I can even try and take a stab at this if you like. I'm an okay
designer, and rock solid web developer.
> 5) How can the wiki documentation be copied back to the Gambit
> manual? When should this happen?
I guess that depends on how easy it is to copy back. Something
occurred to me however. Most user-level comments, questions, and
additions to the documentation would probably live outside of the
texinfo section--by virtue of being harder to understand then normal
wiki content, whereas the texinfo sections might be reserved for
documentation that would actually make it into the Gambit manual. As
wiki content gets accepted into the manual, it would move into the
texinfo sections. This should make exporting those sections a little
easier. I guess the real question then becomes: how do you export a
chaotic batch of wiki pages into an ordered manual?
Overall, i must say that I applaud the movement towards a wiki. It
is a great way to foster contribution and community. Posting a little
code snippet or example on a wiki is easy to do, and has a relatively
low barrier to entry. Lord knows, I'll do my best to write
documentation and help out.
More information about the Gambit-list
mailing list