This was started in another topic… but so as to not continue to hijack that topic… I will start a new one.
What does anyone think about building a website that contains “white papers” with detailed step by step instructions on how to deal with various XOJO situations, things that are NOT discussed in detail in any of the current XOJO documention.
I am talking (for example) of things like
How to prepare you OSX for the Apple Store (manually and with tools like AppWrapper)
How to make your OSX app Retina Ready
How to create a proper Installer for your Windows App
etc.
Papers would be platform specific where necessary, but it would be good to have complementary documents where similar functions are required for both OSX and Windows (and Linux) but where the knowledge base exists in different developers.
This way we could all have a one-stop resource, that could be kept up to date (sometimes it is difficult to piece instructions together from forum topics, and know which information is up to date and which is not)
A Wiki is a great thing to have. I am a long time Emacs and Tcl user. Both have outstanding wiki’s.
With a Wiki, it will quickly get out of control, dirty, hard to find anything, tons of duplicate pages, etc… if there are not enough individuals who will volunteer to help administer, update, edit, move pages, combined pages, reorganize, etc…
It also takes a user base that will not be offended if their page is combined with another, moved or recategorized.
Well first of all, definitely not a Wiki. Wiki’s don’t work out. There have been a number of Xojo / Real Studio wikis in the past, and even the official Xojo wiki has barely worked out.
I’m thinking something more along the lines of RBLibrary / RBGarage. I don’t really want to get into details, but I’ll say I’m not looking to clone either. RBGarage was a fantastic resource, but had a number of problems I don’t want a repeat of.
I’m still in the early stages so the concept if very malleable. This discussion could very well impact the direction, but I just don’t have anything I’m ready to discuss yet.
How well a Wiki will work … I don’t know …
But correct me if I am wrong here Thom… but you sound like you are talking a commerical (paid) endeavor?
If so, that is NOT what I am advocating… I am looking at a FREE situation.
Yes it would have to be monitored… kept clean etc…
And I am not imagining a site that would host code (other that code contained as snippets within a larger white paper)
And to me… a “white paper” is authored by one or more people on a specific subject. Those people are the only contributors to THAT paper… If someone else has an alternative description of the same task, another white paper is submitted, with information that compares/contrasts this new data to the old (so the reader knows why they should/might use one solution over another)
There would be no “selling of software”… A paper could refer to a 3rd party tool (MBS or AppWrapper for example) as long as the document was an step by step explanation of how to do something that is not easily descerned from that products own documentation… but the major focus would be on HOW and WHY things should be done so the reader is educated, not spoon fed.
Jeremy,
that is why I offered to create a freely available pdf.
People send in the steps - I create the pdf - I make available the pdf.
If anything changes - someone lets me know, and I update the pdf.
The pdf’s could still be made available through a website - but at least this way - there are no pages to update or get duplicated.
There would simply be ONE pdf which gets update as-and-when required.
I will def be making myself a STEP-BY-STEP pdf file, if the steps required ever come to fruition that is. That way, I have something I can refer to immediately.
Has anyone spent time on the Tcl wiki? It is loaded with information. The problem with PDFs is you will have exactly that, one persons interpretation of how to accomplish a given task. A wiki will start with one persons interpretation, followed up by another persons improvements, followed up with a totally new, better way of doing it.
I think it’s doomed to fail if it s a white paper type solution. I think it’s doomed to fail if there are not at least 2-3 individuals willing to commit to 1 years maintenance of a wiki.
A properly run wiki is a gold mine for a language. I poorly run wiki is not a determinant to a language, but it is of no benefit either.
Thom, I differ strongly with you on your opinions that wiki’s do not work out. Emacs and Tcl are what they are today because of their wikis. That said, as I already suggested, they are maintained. One persons endeavor to a Xojo/RB wiki is sure to fail, I totally agree.
Richard, I personally think that would be a hard way to go. I see a single Tcl wiki page edited 5, 6, 7 times a day by that many users contributing bug fixes, updates, alternative ways of doing things. If you are going to spend the time to organize the PDFs and such, why not just spend the time helping organize the wiki a bit? Divide the load amongst many people.
A well run wiki can present information much nicer and easier than a PDF ever could. Searching, fly outs, back links, navigation, history, …, the list goes on.
That, however, is just my opinion. Hopefully this thread will get quite a few peoples opinions.
Ok… based on above comments… looks like it is doomed to fail… was just an idea…
Personally I don’t like the idea of “anyone” being able to add content to a specific wiki page. You get people who think they know more than they do, and bad data gets in… you have egos where one person will delete or alter previous data…
A white paper solution is exactly that… One persons interpetation of a solution… if others have ideas… they submit a paper that details their solution, and why it may be a better alternative… without disrupting the original contribution.
No need to “divide the labor”… you wrote a paper… you maintain (or not) your paper.
Sure there would need to be a curator to delete spam etc. as those thing would happen.
Don’t let me stop you guys, I’m just one person with a single idea, if you think a white paper solution is great, then go for it! It certainly would be a great resource! BTW… On the TCL wiki, I don’t see that happening.
Jeremy,
maybe I am looking at it from an over-simplistic angle.
I was referring to relatively straight forward things which would not change that much on a regular basis.
Example - the MAS steps.
The pdf would not be a how to code kind of pdf, - it would simply explain what the MAS is, how the certificates etc work, how to get your certificates etc. etc.
I only have one request. DON’T make a timelined type thing where all old information is kept visible, like a forum sticky, where you have to page multiple times and try to figure out information is TRUE and what is FALSE, or not current etc. This is how the old MAS advices were done and it was awful, to me at least.
I don’t like PDF’s because PDF’s have an illusion of permanence, and the changing landscape of many things is hardly permanent. Following, people would have old versions of the PDF’s and they’d get confused, post, and be told “get the latest version of the PDF” - a waste of time and contributes to confusion.
I like Dave’s basic idea. HTML white paper, where the SOLUTION is always current, with notes about history more toward the bottom as that is ancillary. No one cares about history when they are just trying to solve a problem with TODAY’S situation.
One (MAYBE two) persons are the authors and they are responsible to either keeping that single page CURRENT or if they don’t have time - let it lapse - they need to find someone to take responsibility for it. The page must be edited, removing guessing and questions by other people. I want authority, not a conversation.
The goal: a single HTML page, solving a problem, usually denoting a step-by-step with perhaps an example or two, with the intention of giving brief but thorough, complete but simple, solution to a task.
OK, I probably misunderstood the nature of the request. I am thinking everything and anything. For example, want to compute the phase of the moon? There are at least 3 different ways of doing it on the Tcl wiki, all with various merits. Want to know how to build a large string in memory? There are multiple ways of doing that, again each with their own merits. How to parse a CSV file, how to compute distance and bearing from one lat/lon to another, how to read from an NNTP server, how to compute the best possible solution to a tic-tac-toe game… just a few examples of recently edited wiki pages on the TCL wiki. I guess that is the type of solution I was thinking of.
Look, in the past these needs were met by books. But that isn’t feasible anymore, since everything goes at the speed of the Internet and ANYTHING permanent has the disadvantage of being outdated.
The solution is to maintain a changeable but managed “book” online, where each 'white paper" is one HTML page (or set of pages, but really only should be one, otherwise the topic is too big for the paper itself ) that represents a Chapter or a section of a Chapter that used to be in a printed book.
[quote=85144:@Garth Hjelte]The solution is to maintain a changeable but managed “book” online, where each 'white paper" is one HTML page (or set of pages, but really only should be one, otherwise the topic is too big for the paper itself ) that represents a Chapter or a section of a Chapter that used to be in a printed book.
[/quote]
Or just have lots of loosely connected things that are searchable enough.
