• Open Menu Close Menu
  • Apple
  • Shopping Bag
  • Apple
  • Mac
  • iPad
  • iPhone
  • Watch
  • TV
  • Music
  • Support
  • Search apple.com
  • Shopping Bag

Lists

Open Menu Close Menu
  • Terms and Conditions
  • Lists hosted on this site
  • Email the Postmaster
  • Tips for posting to public mailing lists
Re: WebObjects documentation site
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: WebObjects documentation site


  • Subject: Re: WebObjects documentation site
  • From: Ian Joyner <email@hidden>
  • Date: Tue, 3 Jul 2007 10:34:07 +1000

I appreciate the effort to provide a better level of documentation at the objectstyle confluence site. However, I'd have to say, I like the look of the wikibook a lot better (even though it wastes space on the LHS). Is it possible to give a confluence site a better look, or is this locked into confluence?

One problem is the font. I think it is being killed by anti-aliasing making some characters look semi-bold (eg a, y, h) and thus ruining the reading experience. If I make the font size bigger (command-+), it does not look so bad, or smaller seems to get rid of the anti- aliasing. Does anyone know what font this is (can't see it in the "view source")? (Looks like some wacky Microsoft font.) Looks alright printed, although I'd rather a serif font for printed material.

Another problem is that when there are images that are wider than the page, the text does not wrap, so I'm constantly scrolling to read the ends of lines. Sometimes making the page wider helps, but long lines are not good for readability. (Maybe, this is just something contributors need to be aware of.)

Improvements in the area of formatting and font would be much appreciated.

Ian

On 03/07/2007, at 12:34 AM, Steven Mark McCraw wrote:

Hi all,

A small group of people have begun to look into the problem of lack of good, easy to use documentation for WebObjects and wonder, and based on feedback from the developer lists, we have created spaces at http://wiki.objectstyle.org/confluence/display/WO/Home for the documentation. Right now those spaces are all empty, and almost none of them have been claimed by an author to fill them. We are hoping that people will see a topic that they know a great deal about already or want to learn a great deal about, and fill in the gaps.

If you've already written something on a topic, please post it here. The speed of this process depends on the willingness of the community at large. If just a small handful of people are committed, it will take a very long time to get a useful consolidated reference library in place, and we run the risk of the technology developing faster than the documentation. However, if everyone steps up and contributes even a little bit, we will quickly catch the documentation up to the technology, and develop a great resource that everyone benefits from. This is everyone's opportunity to contribute to the community that they already benefit from.

There are plenty of good reasons to contribute to this effort: It's a great way to say thanks to all of the people who have sacrificed their time and resources to create, free of charge to you, a codebase that enables you to remain up to date and competitive in the web application marketplace while still using WebObjects. It's a great way to exchange information: in return for taking 8 or 9 hours to write a good article on something you already understand well, you get to digest information on a topic you know nothing about in a fraction of the time you otherwise would have had to spend to learn it. If you were willing to spend thousands of dollars for a trip to San Francisco to attend a developers conference which had only a tiny amount of time to present cutting edge information, surely you can spare a work day or two (or a week of evenings perhaps) contributing information to a resource which makes all of this information available to others (and yourself) at a pace that's easy to digest, and a breadth that could never be covered at a single conference.

There are even valid selfish reasons to contribute. If you know nothing at all about a specific topic, writing an article on it is a great way to focus your attention to learn it. If you know only a bit about a topic, by the time you finish authoring a well constructed how-to in print, you will know it extremely well. You will gain respect and gratitude from the community, and it reflects well on the community as a whole. And if everyone does their share, you'll be able to learn from others on any topic you need to know about without having to do it the hard way (endless googling + trial and error). If everyone tries to help, then the jobs and lives of everyone who develops with WebObjects will be happier and more productive.

Finally, please do not feel that you are too limited in your capacities to make a worthwhile contribution. Any sincere attempt to contribute is better than no attempt to contribute. The wiki and all its new entries are being monitored by people who have been programming with WebObjects for close to a decade now, and by the authors of project wonder. If you make a mistake in your documentation, it will be caught and corrected quickly.

We are asking people to denote that they are working on an article before they start writing it, so that we won't be duplicating each other's efforts (it's a big enough task if you only do it once!). Therefore, we ask that before you claim a topic, you ensure that you have the time and resources available to compose it in a timely fashion (say, two weeks?). We just don't want willing people to avoid authorship of a topic because someone has already claimed it, and the claiming person is never actually getting around to doing it.

To contribute to the wiki, you will need to set up an account. Just go to http://issues.objectstyle.org/jira/secure/Signup! default.jspa to create that account. When you have chosen a topic that you want to write on, edit the entry for that topic and change the '**' on the end to '(under construction)'. As soon as you have your article in place, you can just remove the '(under construction)' from the title.

A large amount of information on many of these topics already exists here and there about the web, and we are hoping to collect it all here in the form of easy to understand step by step how-to guides. If you claim a topic, please feel free to incorporate any of the information which already exists at http://en.wikibooks.org/ wiki/Programming:WebObjects (the reason we are not simply expanding this site is that there was a strong consensus that the formatting options and general ease of use of the wiki was not as good as that of the confluence wiki at objectstyle.org). A good example of the kind of article we are hoping for is http://wiki.objectstyle.org/ confluence/display/WOL/Create+a+new+WO+Application.

Screenshots are a good idea, and simple instructions are also good. If you choose to write an article about how to add a google map to a web page, the reader should be able to get a good idea of what they are, how they work, how to add them, how to acquire an api key, pros and cons of using them in various ways, configuration options, how wonder simplifies the process, etc. by the time they have read it. It should ideally be thorough enough to satisfy the curiosity of either someone who wants to know all about it, or just someone who needs to know the nuts and bolts to finish a feature for a project they are working on.

Finally, the hierarchy of articles is not complete, and likely never will be. If you can think of a topic that is missing, please add it, and hopefully someone (perhaps yourself!) will fill in the content in then near future.

Thanks,
Mark
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
40sportstec.com


This email sent to email@hidden



_______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list      (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden


  • Follow-Ups:
    • Re: WebObjects documentation site
      • From: Andrus Adamchik <email@hidden>
References: 
 >WebObjects documentation site (From: Steven Mark McCraw <email@hidden>)

  • Prev by Date: Re: Batch faulting
  • Next by Date: Re: Subclassing EOEditingContext
  • Previous by thread: Re: [Wonder-disc] WebObjects documentation site
  • Next by thread: Re: WebObjects documentation site
  • Index(es):
    • Date
    • Thread