User Doc Wiki

Moderator: Jim

User Doc Wiki

Postby Jim » Thu Aug 05, 2010 9:55 pm

This is a follow-up from here.

(For those who don't know, there is a user-editable API documentation wiki here. If you're interested in participating, please let us know.)

Dan Rathbun wrote:Wow this thread is all over the place.. but interesting.

Jim's Wiki API is an experiement. I played with one of the ConstructionPoint class, and came to the conclusion, it's just way too labor intensive. It relies too much on people following a set of style rules.

I did an automtic API some years ago using CSV data and HTML Tabular Data Controls that auto generated the API page. I wasn't satisfied (although it worked.) I always wished to update it to XML. Add the entries into the xml would be via a webform (check boxes, cut&paste boxes, etc.) then later on the API doc (either web or CHM,) would be generated from the XML (however PHP, RUBY take your pick.)

Editing would be similar, the method data would be displayed in an edit form.

Anyway the style of the API pages would be controlled thru CSS, and all pages, classes, would be displayed the same.


If editing manually (online) there is definitely a compromise that is made. If more than a handful of markup tags are needed, no one is going to remember them or use them.

The Wiki files are stored in a mercurial repository and can be sync'd to your local copy, edited, and then change-sets pushed back to the main repo. This is beneficial because you can use your favorite editor to edit the pages instead of the online interface.

Automating was an idea I had in mind from the beginning. Ruby scripts which build the wiki pages can also be stored in the repo, but the only files ending in .wiki will be shown.

But then if everything is designed to be edited or automated locally, the collaborative features of a wiki are completely lost. This would be a net loss IMO. The collaboration is what is going to make the docs exceptional and so needs to be available.

So if automation is desired, it needs to be 2-way: changes made via the online interface need to be preserved in the process.

(damn, now I wish I could move this to the skx forum.)
0
Hi

Jim 
Global Moderator
 

Re: User Doc Wiki

Postby Jim » Sat Sep 04, 2010 5:59 am

I already generated a ruby file for each class in the API, with methods. Wwuld it be preferable to use an RDoc, yard, or natural docs system to generate docs from this mock-up code of the API?

http://code.google.com/p/skx/source/bro ... kup#hg/lib
0
Hi

Jim 
Global Moderator
 

Re: User Doc Wiki

Postby Dan Rathbun » Sat Sep 04, 2010 9:58 am

Did you see the RDoc-Darkfish output in the Ruby CHMs from the latest installer packages ?

RUBY PROGRAMMING REFERENCES
0
    I'm not here much anymore. But a PM will fire email notifications.
    User avatar
    Dan Rathbun 
    PluginStore Author
    PluginStore Author
     

    Re: User Doc Wiki

    Postby thomthom » Sat Sep 04, 2010 10:20 am

    Jim wrote:I already generated a ruby file for each class in the API, with methods. Wwuld it be preferable to use an RDoc, yard, or natural docs system to generate docs from this mock-up code of the API?

    http://code.google.com/p/skx/source/bro ... kup#hg/lib

    I'm currently using Yard - I found RDoc-Darkfish to be troublesome getting the output and formatting I wanted.
    0
    Thomas Thomassen — SketchUp Monkey & Coding addict
    List of my plugins and link to the CookieWare fund
    User avatar
    thomthom 
    PluginStore Author
    PluginStore Author
     

    Re: User Doc Wiki

    Postby Chris Fullmer » Mon Sep 06, 2010 4:53 am

    There was an entire breakout session at basecamp about how great it would be if we could make our own editable API. I quickly jumped right in with a link to this project and explanation of what we are trying to accomplish. Everyone sort of nodded their heads and said "ok", then off they went explaining how maybe we could try to use github to make an editable wiki style api document, and how great it would be if the community started some sort of editable API doc.......I felt a little ignored. I even showed it to Barry Janzen (of the Google SketchUp team) and he liked it. But I'm not sure anyone else around the circle quite understood that I was telling them that there was already an effort underway by the community to make a complete API that could be edited and updated by the community. They spent 20 minutes brainstorming on how to do what this project is already doing, and how important it would be to get the whole community involved. duh, here it is. Maybe I need to email each one of them separately and tell them AGAIN about this project.
    0
    Lately you've been tan, suspicious for the winter.
    All my Plugins I've written
    User avatar
    Chris Fullmer 
    SketchUp Team
    SketchUp Team
     

    Re: User Doc Wiki

    Postby thomthom » Mon Sep 06, 2010 7:08 am

    Tell'em, nag'em. :D
    0
    Thomas Thomassen — SketchUp Monkey & Coding addict
    List of my plugins and link to the CookieWare fund
    User avatar
    thomthom 
    PluginStore Author
    PluginStore Author
     

    Re: User Doc Wiki

    Postby Jim » Mon Sep 06, 2010 4:44 pm

    Developers are problem-solvers. Their minds were probably going crazy with the thought of developing and implementing some awesome user-editable document system (i.e. a wiki,) rather than actually contributing to some boring project already underway.
    0
    Hi

    Jim 
    Global Moderator
     

    Re: User Doc Wiki

    Postby August » Tue Sep 14, 2010 4:59 am

    Jim wrote:Developers are problem-solvers. Their minds were probably going crazy with the thought of developing and implementing some awesome user-editable document system ...

    Ouch.

    I wasn't even at that base-camp session and this one stings a little. (IIRC, I think it was opposite "How to quit your day job" which seemed more important at the time.)

    I am very glad to find out that this project is already underway. I hope I can contribute to it. Two years ago, when I got laid off from Install Shield, I described my "ideal job" as "Taking some legacy doc that can no longer be maintained and developing an automated way to convert that into a wiki so that it can be maintained, if only by the user community." Well, here it is. (Unfortunately, there's no salary involved.)

    To fit my "ideal job" fantasy, I would get permission from Google to use their current doc as source material, with suitable caveats, disclaimers, etc., and then set about using that to populate the empty pages in the current wiki so that we would have at least a starting point instead of having to regenerate it all.

    My ideal system would monitor the Google pages for changes and flag the wiki pages whenever Google updates their version. That keeps responsibility for the Google doc with Google, absolves them of any responsibility for even notifying us of changes, and yet lets us stay on top of whatever they do.

    Maybe that's overly ambitious. You tell me.

    Sounds like some of the folks reading this thread know the current doc-gen tools better than I do at this point. For me it's always been roll-your-own or RoboHelp because the folks paying the bills seemed to always already have RoboHelp in house. (And aesthetically I really don't like RoboHelp any more than I like MS-Word, but I've been able to make it do what I need it to do, like I do with Word.)

    Assuming that we/I can get permission from Google, or at least a non-litigation promise from John Bacus, are there usable tools already available to help with this conversion?

    Is this even the right direction?

    If you want credentials, you can see some case studies of other, related projects that I've done at http://www.KiloPages.com.

    I hope this helps,
    August
    0
    “An idea, like a ghost, must be spoken to a little before it will explain itself.”
    -- Charles Dickens

    August 
     

    Re: User Doc Wiki

    Postby Jim » Tue Sep 14, 2010 1:47 pm

    August wrote:Ouch.


    It was meant to be complementary, and slightly humorous.

    I'm just using the wiki as a personal notebook; adding things as I go that are not obvious, or that don't work as I expect; as well as making links between entries because the official docs lack these fundamental connections between classes.

    Most folks can get what they need from the documentation, and a little help in the forums. I don't feel there is any great demand for the project so I'm not motivated to do much more.
    0
    Hi

    Jim 
    Global Moderator
     

    Re: User Doc Wiki

    Postby August » Tue Sep 14, 2010 5:57 pm

    Jim wrote:
    August wrote:Ouch.

    It was meant to be complementary, and slightly humorous.

    Mine was also meant to be humorous. Sorry I left out the smiley. ;)

    Most folks can get what they need from the documentation, and a little help in the forums. I don't feel there is any great demand for the project so I'm not motivated to do much more.

    That has been the status quo for a long time, documentation that is mostly there except for the glaring holes and users left to thrash until they ask on the forums.

    Yes, it works for those who can make it work -- everyone currently using SketchUp Ruby has run that gauntlet.

    But there also seems to be a growing consensus that something better is needed, to save the time of those using Ruby professionally, to give new users a better starting point, and to not demand so much from the forum contributors. Not to mention saving the nerves of folks like me who just really want to fix it when they see the problems.

    I heard from both Dan and Chris that something was finally getting off the ground, but now I hear from Jim that he doesn't feel there is any great demand for the project so he's not motivated to do much more. That sounds to me like Jim is tossing the issue back out to the community of those who are not satisfied with the status quo.

    Clearly what Chris got at the base-camp session, about getting the community involved, is important. And the infrastructure to support that community involvement is important.

    If this is Jim's private collection of notes, made public, it probably does not have the proper infrastructure for a community project.

    Or does it? I'm not in a position to tell, either what's under the hood in Jim's site or comparing it to what else is out there (e.g., github that was brought up at Chris' base-camp session). Jim's site may have everything we would want except one feature, but if that's a showstopper, there we are.

    A Critical Features list is therefor important, and progress towards that may have been made at that base-camp session. Chris, do you have notes from that session? Or the title of the session to ask Google if they do?

    If copying the Google material into this site, just because this one is editable, will get in the way of what Jim has in mind, Jim is currently the owner, so he gets the final vote.

    If Jim's site will serve, if it looks like a viable platform, I'll get started on what it will take to fill it up. I can certainly start on getting Google acquiescence no matter what the platform.

    Sorry this is more questions than answers. I hope it helps,

    August
    0
    “An idea, like a ghost, must be spoken to a little before it will explain itself.”
    -- Charles Dickens

    August 
     

    Re: User Doc Wiki

    Postby August » Tue Sep 21, 2010 5:30 am

    It's been about a week. I've been in some intense conversations with both Jim Foltz and Scott Lininger. I have sent two requests for comment on the plan to John Bacus and gotten nothing in reply so far.
    0
    “An idea, like a ghost, must be spoken to a little before it will explain itself.”
    -- Charles Dickens

    August 
     

    Re: User Doc Wiki

    Postby Jim » Thu Oct 28, 2010 3:03 pm

    So, is the wiki up to the task? I say probably not, but I haven't spent much time investigating alternatives.
    0
    Hi

    Jim 
    Global Moderator
     

    Re: User Doc Wiki

    Postby August » Fri Oct 29, 2010 1:35 am

    Jim wrote:So, is the wiki up to the task? I say probably not, but I haven't spent much time investigating alternatives.


    Sorry; I've let this gather dust for a few weeks. And, with any luck, I will be starting a full-time job soon so this will be more on the back burner for me.

    I have not heard back from John Bacus with a yay or nay, so my plan is to explicitly tell him that I intend to do something along these lines, presumably hosted on a Google platform, and that I will include a disclaimer that Google, Inc. is not maintaining it (i.e., use at your own risk, the official doc is <here>). I will accept the absence of a "STOP" from him as a tacit "go ahead". But I'm not going to take that step until I have the infrastructure question settled and some kind of proof-of-concept working.

    I spent a while researching various web-markup alternatives with the idea that the underlying Google doc could be left as is and those who actually use it and find out where it is lacking could add comments to it. That is, in essence, the status quo, except it would move the comments up to the top of the page, in a sidebar or floating comment box, more closely associated with the original text.

    However, we are talking about REFERENCE DOC here, not a development effort, not a conversation. Comments are really not the best way to update Reference Doc, ideally the doc itself would be updated to simply give the corrected, completed, or enhanced information. Otherwise the user is looking at a markup, a highlighted and red-lined version with floating bits of text to mentally insert in the middle of some key sentence, etc. Not User Friendly.

    With that concept of Reference Doc in mind as the better goal, I've given up on the idea of markup as being fundamentally less than ideal.

    On the other hand, Scott appears to have been inspired by the various markup alternatives that I found and has begun lobbying those who do the doc platform to provide better commenting tools that go well beyond the all-at-the-end that exists now. That may indeed help things, regardless of any Wiki.

    Having decided that *A* Wiki, or other collaborative doc, not conversation, is probably the best way to go for reference info, I have not yet explored whether or not the "current" Wiki meets the practical requirements of being able to populate it from the existing Google API doc and then have a flexible number of people be able to edit what is presented.

    I would also like a way to flag, in the Wiki page, whether or not the base Google API doc has changed from the version on which the Wiki page is based. Being able to identify the nature of those changes would be a bonus. That widget may or may not already exist for this or other Wiki infrastructures.

    Those are, I believe, the gating functions determining whether or not this will be both easy and useful in the long term.

    The current Wiki was generated by Jim creating pseudo-code that simply had placeholders for all the methods and then using a doc-generating tool to create Wiki pages from that. To populate that Wiki with the current Google API doc as a starting point will probably need different tools. Otherwise you're looking at converting the current Google doc into source comments to allow it to be read by that tool and filled into the Wiki. That seems the long way around the barn unless the tools are already built. (Going around the barn does not matter if you're on a well built track.)

    I know of many tools that go from source comments to formatted text, but none that go the other direction, so I think it will just as effective to go from the Google API doc into the Wiki, without creating a pseudo-source version of it as an intermediate step to be able to use the previous Wiki-building tools.

    I suspect that widgets for identifying whether or not the content of some URL has changed exist, I don't know whether they exist for Wikis or for the current Wiki in particular. I don't know if any of them flag the changes.

    Thanks for asking, Jim. I had been meaning to post a status for a while.
    0
    “An idea, like a ghost, must be spoken to a little before it will explain itself.”
    -- Charles Dickens

    August 
     

    SketchUcation One-Liner Adverts

    by Ad Machine » 5 minutes ago



    Ad Machine 
    Robot
     



     

    Return to Skx Extension Library

    Who is online

    Users browsing this forum: No registered users and 1 guest

    Visit our sponsors: