Re: WebObjects documentation site
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