Elizabeth Matthis wrote:
It's great of you to express your interest in the OOo wiki. I'm sure
one of the developers will get back to you, but most likely tomorrow
because they are almost all on German time (6 hrs ahead of EDT; if you
still live near MIT)
Hi Liz.
I'm still in the same timezone, and often a stone's throw from my alma
mater.
As for me, I can say for sure that updating info on the wiki is an
important task that really needs attention in more places than just
this one. So don't be shy and jump right in.
*ding* Another great example:
http://wiki.services.openoffice.org/wiki/Architecture/Source_Code_Inventory
Which, unfortunately, also appears to be moribund, showing no activity
since September of 2007. But I like its observation, "experiences with
the project have caused concern over the existent 'barrier of entrance'
for potential contributors".
And, yes, the issue of versions changing and the wiki not changing and
accumulating debris is an problem. How would you suggest fixing it?
See, I'm always looking for answers. I'm on the user experience team
where design meets implementation daily ;-) and I would love for the
OOo wiki to improve.
As to how one tracks commentary/documentation to the actual code, I
think a little hint from Don Knuth's "Literate Programming" is in order:
http://www.literateprogramming.com/
One current example of it is Javadoc, and I see some hooks in the OOo
code that would support a processor running over the source (a la
Doxygen or any number of other parsers). Someone gave me a link (which
I've lost) on #dev.o.o to a site that posts Doxygen output, and it was
interesting to look at. But Javadoc on its own isn't sufficient, for
reasons mostly of scale. For example, I didn't find any use of a
summary or main page. Instead, one was dropped right into a complex
list of functions and files and monster diagrams. A problem of seeing
the forest for all the trees.
The hard part is figuring a "literate" mechanism that collects and
indexes all of the smaller blobs of documentation into one (or more)
narrative streams that actually make sense to the reader. Put another
way: getting programmers to document code is hard enough; getting them
to make changes to multiple sources is doomed to failure; but maybe
getting them to document once lin a particular way could work.
Take for example the wiki entry on Process Flow I cited earlier:
http://wiki.services.openoffice.org/wiki/Architecture/Process_Flow
Here's a trim, hierarchical, narrative view of what happens in OOo at
startup at the birds-eye view. But is it current? Is it so general
that it can't really be wrong? Or is it subtly wrong in some misleading
way? Can't tell.
You might imagine this being somehow derived from the code, perhaps
augmented by code plus a profiled run. The devil is in the details: one
platform's "dead code" is another's special sauce (e.g., the sal/ hooks
for each OS supported), so to get a good view of what happens you would
need to take the system variants into account. And this is where a
human hand typically comes in to play, and we're back to the issue of
documentation maintenance.
In fact I did a wiki usage survey not too long ago and one of the
points users made was that there was a lot of obsolete stuff on the wiki.
I think a cue can be taken from {OpenGrok here. Rather than trying to
have a static wiki page, documentation would be derived from the
source. Thus, there would be documentation that is "correct" for
DEV300_m43, DEV300_m48, DEV300_mXX, and whatever other "active" branches
might exist. I'm still dancing around the method(s) for getting all of
this pulled together in a sensible manner. But I am lead to another
side observation:
Aside from the [L]GPL at the top, comments are pretty sparse in OSS
code.
At least, in my experience. This isn't unique to OOo; a lot of other
GNU and OSS seems to favor no comments over any. Perhaps this is a nod
to the multi-lingual nature of OSS. Perhaps it's just laziness. Or
perhaps both. But I haven't seen an explicit reason to avoid commenting
code. We all know that saying "add one to i" next to "i++;" is stupid.
But a bit more description of that a bit of code is *expected* to do
would be handy - we can usually tell what it actually does by inspection.
Anyway, does anyone care to offer some history as to why both of these
architectural pages seem to have fallen quietly by the side?
Thanks!
-Del
Del Merritt wrote:
This page is pretty awesome:
http://wiki.services.openoffice.org/wiki/Architecture/Process_Flow
Would someone have the time to pass on some source references? E.g.:
1.1.1 Bootstrap the initial Uno component context (Unos root
object). [unotools/source/config/bootstrap.cxx]
Assuming, of course, that's a correct reference. I'd be happy to add
them to the wiki as I'm learning how design and implementation meet
each other. Similarly, if there are specific/notable changes - the
page was last updated in January of 2007 - I would be happy to add or
update information accordingly.
Of course, there's the question of which version(s)/baseline(s) of
OOo the wiki should reflect. I don't know if this problem of change
control is addressed well in any wiki.
-Del
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
