[svlug] GIOVANNI RE'S MODEST EVOLUTIONARY DOCUMENTATION PROPOSAL - Re: Understanding the problem... jor

[giovanni_re]

==  GIOVANNI RE'S MODEST EVOLUTIONARY PROPOSAL
==  (akka  GIOVANNI RE'S MODEST EVOLUTIONARY SOFTWARE DOCUMENTATION VIA
WIKI PROPOSAL)

1)  PUT A WIKI UP ON EVERY SOFTWARE PROJECTS WEBSITE
1A)   WHICH DOESN'T REQUIRE A LOGIN TO EDIT  -  JUST LIKE WIKIPEDIA
2)  INCLUDE THE ENTIRE WIKI IN EVERY PACKAGING OF THAT SOFTWARE
2A)   ACCESSIBLE OFFLINE VIA A "WIKI" ENTRY ON THE "HELP" MENU.
2B)   & ONLINE VIA A "WIKI-LIVE" ENTRY ON THE "HELP" MENU.


=====
Hi Akkana :)

> I'm a big fan of understanding the roots of a problem and solving it
> on that basis. Because I am, I waste many days chasing down problems
> that ought to "just work", and probably would "just work" if I
> gave in and installed a bone stock Ubuntu Gnome desktop with no
> customizations.  

> Understanding this stuff *shouldn't* take days of wasted time -- but
> it does, because none of this crap has decent documentation.  


Great thoughts! :)  

I've long thought this myself, & now I'm suspecting I see a practical
solution:

==  DOCUMENTATION PRACTICAL SOLUTION:  WIKIs
==  akka "GIOVANNI'S MODEST EVOLUTIONARY PROPOSAL"

Basically, a way to make documentation creation so easy that almost
everyone can create it with almost no effort, will result in more useful
documentation being created, & this will make the world a better place.

How:  All software projects should have wiki pages just like wikipedia. 
Ex: Ubuntu, NetworkManager, ... every distro & every major subsystem &
every apt installable application.

The nice thing about this is it doesn't take any central authority to
make it work - any project can start a wiki today (or any day) on their
website & the process of creating documentation has begun.  (Stage2 is
to somehow get the wiki included _into_ the application - as an addition
to the "Help" menu selection for an application.  Every debian
application should include a snapshot of that ap's wiki, installed with
the application, & stage 3 would be to make that a live connection when
the person is internet connected, so viewing (or updating) the wiki is
just a click away when you're using the ap - just click on the "wiki"
entry under the main "Help" menu entry for every application sw window,
& it pulls up live the application's wiki page in a web browser.)

You know I'm being very brief in my sketch in that last paragraph, but I
think that is a _SUPER_ powerful idea, one that would
evolve/upgrade/move the entire free software community up an entire
evolutionary developmental step/level.


==  GIOVANNI RE'S MODEST EVOLUTIONARY PROPOSAL
==  (akka  GIOVANNI RE'S MODEST EVOLUTIONARY SOFTWARE DOCUMENTATION VIA
WIKI PROPOSAL)
We can call the above idea: "Giovanni Re's modest evolutionary proposal"
 (short for "Giovanni Re's modest evolutionary software documentation
via wiki proposal")

1)  PUT A WIKI UP ON EVERY SOFTWARE PROJECTS WEBSITE
1A)   THAT DOESN'T REQUIRE A LOGIN TO EDIT  -  JUST LIKE WIKIPEDIA
2)  INCLUDE THE ENTIRE WIKI IN EVERY PACKAGING OF THAT SOFTWARE
2A)   ACCESSIBLE OFFLINE VIA A "WIKI" ENTRY ON THE "HELP" MENU.
2B)   & ONLINE VIA A "WIKI-LIVE" ENTRY ON THE "HELP" MENU.

One other idea: Maybe there should be a meta organization, "Free
software project wiki management", that provides a management structure
for this sw running on a project's website.  It is the social
organization that oversees all the social aspects managing this wiki
capability for all free sw projects: like the wikipedia organization
does for the wikipedia, with analyzing operations, & setting policy, &
creating editor hierarchies, etc.

:: Point: No login required to edit.
Fact:  I've made maybe 10-20 updates to wikipedia.  I did them because
it was this easy to do: I clicked "edit this page".  If I'd have had to
create a login, I doubt I would have yet made even one contribution to
wikipedia.  It would have been that much a barrier to contribution.  I'm
just too busy.

I suspect it is the same with creating software documentation:  Make the
barrier to entering documentation == 0, and decent enough, usable,
documentation _will_ get produced.  Make the barrier > "click 'edit this
page'" &, basically, roughly zero documentation will get produced.

Then, more ducumentation >> more readily accessible info for users >>
more comprehension of the sw that exists >> more debugging >> more fixed
bugs >> better software.

[Yeah, I like ducumentation.  ;)  ]


So, now, when _you_, Akkana, _spend_ the time to learn something, if you
ad a wiki documentation entry, the next person looking to learn about
that can learn from your mental effort, & your effort wont be "waste"d
(your word), it will have been _invested_, and create a positive
_return_ for society.  And, some other person's investment will create a
return for you. & on & on.  -  akka - the free sw development model
applied to free documentation.  ;)   :)



==  WIKI CURRENT _NON_ EXAMPLES
For example, note that:
1) The Ubuntu wiki is _not_ a wiki about the Ubuntu system, it is a wiki
for the "community teams".  The correct implementation would be to make
the Ubuntu wiki about _all_ things Ubuntu, & the "community teams"
section of the Ubuntu wiki would be a section about the cts. - and
eliminate the login.
https://wiki.ubuntu.com/


2) NetworkManager has no proper wiki - it should.
http://projects.gnome.org/NetworkManager/
(Their wiki link directs to
http://live.gnome.org/NetworkManager
which requires a login - bad. No login should be _needed_. Just like
wikipedia.  _That_ is the essence of getting the valuable documentation
contributions - the barrier to entry needs to be only clicking on "edit
this page".)


3) Do HAL & UDev have wikis?  They should.
http://www.freedesktop.org/wiki/Software/hal
  -  login required.  Fails.
http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html
  -  no wiki >>  Documentation fail.


["Fail"s.  Yeah.  Trendy.  ;)  I like the word "fails".  ;)  ]



4) Look - Debian has a defective wiki - it requires a login
http://wiki.debian.org/DebianWiki

I/people just arn't gonna bother to create & remember a login for every
project.
See, if it didn't have a login, I might have edited this page
http://wiki.debian.org/Network

to add "NetworkManager" as a link, & created that page, & put on there
"there seems to be a bug in NetworkManager, or maybe in the KDE
implementation of it, found in my using KUbuntu 10.04, when closing my
laptop lid caused the networking to be unreenably disabled", and put a
link to my SVLUG & KDE list posts, which would have alerted users to
this problem, & maybe the developer who might could investigate or fix
it too.

Point: their having a login cost the debian project, & the
NetworkManager project, & all the users of Deb & Deb derived distros of
knowing about, & working toward, having a fix.  too bad for them all. :(


5) _Everything_ (of any minor or larger significance) should have a
wiki.


6) Akkana - maybe you could get one started here!  :)   With a link on
the home page:
http://www.gimp.org/
http://www.gimp.org/docs/
http://www.gimp.org/develop/


==  BerkeleyTIP  FREE SOFTWARE & FREE CULTURE
BTW, this is related to my having created the BerkeleyTIP group (about
Free Software, Free Hardware, Free Culture) specifically as a group to
include free culture along with free software - because I suspect that
these are currently two distinct topics/activities which I suspect will
in short time merge into a single "Free Software/Culture"
activity/experience.
http://sites.google.com/site/berkeleytip/


==  NO LOGIN REQUIRED.
So, I'd bet dollars to bits some noob will say "You can't have no login
required. It'll be vandalized.  It won't work."

To which I say: "Wikipedia."

Some combination of "watch change notifications" & editors should reduce
that problem to insignificance, just like on wikipedia.


==
(Akkana: see end below:)

On Wed, 5 May 2010 09:18:43 -0700, "Akkana Peck" <akkana at shallowsky.com>
said:
> I'm a big fan of understanding the roots of a problem and solving it
> on that basis. Because I am, I waste many days chasing down problems
> that ought to "just work", and probably would "just work" if I
> gave in and installed a bone stock Ubuntu Gnome desktop with no
> customizations.  Modern Linux distros (except maybe Gentoo) are
> written with the assumption that you aren't going to change anything
> -- so reverting to the original (reinstalling) will often fix a problem.
> 
> Understanding this stuff *shouldn't* take days of wasted time -- but
> it does, because none of this crap has decent documentation.  With a
> lot of the underlying processes in Linux -- networking, fonts, sound,
> external storage -- there are plenty of "Click on the System Settings
> menu, then click on ...  here's a screenshot" howtos, but not much
> "Then the foo daemon runs the /etc/acpi/bar.sh script, which calls
> ifconfig with these arguments". Mostly you have to reverse-engineer
> it by running experiments, or read the source code.
> 
> Sometimes I wonder why I bother. It may be sort of obsessive-compulsive
> disorder, but I guess it's better than washing my hands 'til they bleed,
> or hoarding 100 cats. At least I end up with a nice customized system
> and more knowledge about how Linux works. And no cat food expenses.
> 
> But don't get on someone's case because he doesn't have days to
> waste chasing down deep understanding of a system problem.  If
> you're going to get on someone's case, go after the people who
> write these systems and then don't document how they actually work,
> so people could debug them.
> 
> 	...Akkana, currently stymied figuring out why SD cards no
> 	longer mount in Lucid without hal -- neither udev rules
> 	nor udisks aka devicekit seem able to create /dev/sdb1

Akkana - suggest to the GIMP, HAL & UDev people to create proper
documentation creating wikis for these projects. :)

&: Please let me know how any of your efforts on this turn out.  :)


[I think it would be so cool, if KUbuntu 10.10 had some wiki
documentation in some application.  :)  ]