Weekly Edition
Return to the Announcements page
| |||||||||||||
Where's the Summer of Documentation? (OStatic)
Joe "Zonker" Brockmeier looks
at the missing elements from Summer of Code. "I bring up documentation, but really the problem that I see is that the Summer programs are simply too code- and developer-centric. Projects and companies in this space should also be thinking about involving translators, user interface designers, artists, and other disciplines in their projects. Not only because it would help these projects be more well-rounded and address areas outside of just developing code, but because it would also provide a wonderful opportunity for cross-pollination. Students who are pursuing other fields of study would provide an opportunity to inform and enthuse ambassadors for open source who move in different circles. It would do open source projects worlds of good to have articulate and interested participants who could carry open source ideals to their peers in other disciplines."
(Log in to post comments)
Where's the Summer of Documentation? (OStatic) Posted Apr 20, 2010 0:41 UTC (Tue) by gdt (subscriber, #6284) [Link] A case in point: Documentation Why isn't there a document available to users describing the principles of operation of printing? Or system start and device discovery? Or interfaces and routing? The lack of documentation hurts development too. I can only think that there would have been less iterations of NetworkManager if it had more documentation.
Where's the Summer of Documentation? (OStatic) Posted Apr 20, 2010 2:43 UTC (Tue) by jmm82 (guest, #59425) [Link]
"device discovery?"
Well, lets we had devfs http://www.linux.it/~rubini/docs/devfs/devfs.html
Then /sbin/hotplug http://linux.die.net/man/8/hotplug
Then udev http://linux.die.net/man/8/udev
udev/hal http://www.freedesktop.org/wiki/Software/hal
and back to plain udev. Oh and we are creating a new version of devfs.
Did I miss anything?
A better question might be how is Dan Williams still have his sanity?
Where's the Summer of Documentation? (OStatic) Posted Apr 20, 2010 18:26 UTC (Tue) by JoeF (subscriber, #4486) [Link]
With what little udev documentation there is, I was able to write some nice rules when I plug in my iPod, etc.
Come udev/hal, things break. No documentation on how to handle this. I am ready to disable hal to get my udev rules working again.
Where's the Summer of Documentation? (OStatic) Posted Apr 20, 2010 19:44 UTC (Tue) by njs (guest, #40338) [Link]
Don't worry, the next release of your distro will probably remove HAL for you.
Where's the Summer of Documentation? (OStatic) Posted Apr 23, 2010 6:01 UTC (Fri) by jmorris42 (subscriber, #2203) [Link]
Preach brother!
They change out device management every distro release it seems, especially Fedora. And if you can find documention on the net for whatever horror they ship this version you have no real way of knowing if the documentation matches the version you have and with the churn rate that is a real problem. The document you find might be for either a newer or older version.
And if you do find enough information to figure out how to fix the breakage you are suffering today, that knowledge is certain to be useless in a few months when it all gets rewritten..... again.
In days of yore, Linux was essentually UNIX and you just grabbed an O'Reilly book. Now there is NO printed doc from anywhere describing the mess of *Kit cruft.
I want to know how any new software is even getting created these days. All of the distros seem to have settled on Python + GNOME for their userspace stuff. Ok, how does one find docs on that? Python + GTK is findable, but GTK != GNOME. Is there a secret manual somewhere Google can't find? Do you have to code with an IRC client open and receive the oral traditions as you need them? Spend all day finding an existing program that kinda does what you want and cut/paste from it with only a vague clue what it is doing and then fix i by trial and error? Or what? And again, forget dead trees, Amazon has zilch that is even halfway current for GNOME in any language.
Which is why my last GUI app was written in Tcl/Tk, grab the book (and keep the ORA pocket ref handy) and Bobs yer uncle. Its old but it works and has good accurate docs.
Of course now wouldn't be the time to write such a thing anyway since the GNOMEs are hellbent of tossing GNOME2 for a new shiny rewrite... that requires GL and thus won't run on wide swaths of real hardware and zero virtual machines. Could somebody take a cluebat to those guys?
Where's the Summer of Documentation? (OStatic) Posted Apr 24, 2010 21:47 UTC (Sat) by oak (subscriber, #2786) [Link]
> the GNOMEs are hellbent of tossing GNOME2 for a new shiny rewrite... that requires GL and thus won't run on wide swaths of real hardware and zero virtual machines.
Incorrect. See: http://live.gnome.org/GNOME3Myths
Where's the Summer of Documentation? (OStatic) Posted Apr 20, 2010 9:50 UTC (Tue) by nye (guest, #51576) [Link]
Documentation is surprisingly hard to get right, and you end up with a cyclical problem wherein the documentation sucks, so nobody reads it, then nobody thinks it's worth updating, because nobody reads it. This is particularly the case with flashy GUI applications because they're developed under the CADT model which never allows time for documentation to catch up to reality, even if anybody cared. A Summer of Documentation would be wonderful, but somehow that documentation would then need to be kept accurate.
I tried to stop myself writing this offtopic rant, but I can't keep it in any longer:
One hint to people writing documentation: if a user asks for context-sensitive help on an option labelled 'autotuning frobnosticating samophlange', the correct documentation is *not* 'select whether or not to enable the autotuning frobnosticating samophlange'. This leaves the use wondering 'do I get a non-autotuning one if I disable it, or no samophlange at all? Is there a non-frobnosticating samophlange? What the heck is a samophlange? WHAT DOES THIS OPTION DO AND WHY IS IT PRESENTED TO ME?'. KDE4, I'm looking at you.
Where's the Summer of Documentation? (OStatic) Posted Apr 20, 2010 11:57 UTC (Tue) by stumbles (guest, #8796) [Link] Lol, so true.
Where's the Summer of Documentation? (OStatic) Posted Apr 20, 2010 20:38 UTC (Tue) by anselm (subscriber, #2796) [Link] KDE4, I'm looking at you. What do you mean, summer of documentation? Decade of Documentation, more likely ...
Where's the Summer of Documentation? (OStatic) Posted Apr 21, 2010 11:38 UTC (Wed) by brianomahoney (subscriber, #6206) [Link]
Another problem which inhibits ease of development are the BIG projects, eg KDE, MOZILLA, OpenOffice for which the build process is arcane and complicated, with the technology we have now:
(a) git clone (or svn, hg ...) (b) ./configure || build.sh (c) make should work for all.
Not the nasty twisted inter-connected set of web pages that has you editing .bashrc ... downloading 15 tool/pre-requisites ... yar de yar ... before you start.
Where's the Summer of Documentation? (OStatic) Posted Apr 23, 2010 22:58 UTC (Fri) by daglwn (subscriber, #65432) [Link]
> with the technology we have now:
> (a) git clone (or svn, hg ...) > (b) ./configure || build.sh > (c) make > should work for all.
You forgot:
Actually, the process should be:
(a) git clone (etc....)
Generally, the simpler the process and the fewer the tools, the better.
Where's the Summer of Documentation? (OStatic) Posted Apr 25, 2010 17:35 UTC (Sun) by wahern (subscriber, #37304) [Link]
`make install' should be enough. The very purpose of make is to ensure that dependent steps are executed before the target.
Even `make check install' will work, but I'm not sure there are any guarantees about which target will be "built" first, so it might install first and then check.
`make install clean' should also work, technically, except that like above it may clean first and then install, rebuilding everything in between. The problem here though is that many makefiles will conditionally include some directives based on the presence of the `clean' target on the command line. makefiles which lack this logic--which is not portable itself--are the reasons why `make clean' in a fresh checkout will often, seemingly incongruously, build stuff before deleting it. To prevent this, some makefiles will check whether the clean target is specified on the command line, and then fail to define all sorts of dependencies, which may make another target, such as `install', fail to build if specified in the same invocation.
One of the problems with the above, though, is that autoconf relies on a "recursive" make paradigm, so a target that relies on dependencies specified in another makefile may rely on those dependencies implicitly. (This can happen in non-recursive make, of course, but it's far easier to spot and fix during development.) Poorly written--or generated--makefiles was the reason that people habitually executed `make [all]' and `make install' separately. These problems are not as common anymore, in my experience. I have almost 100 third party projects, mostly using autoconf, manually installed under /usr/local using plain `configure [...] && make install'.
|
|||||||||||||