Join the Ebuild Documentation Effort!

[drobbins]

Hi All,

 

It's time to start getting Ebuild documentation in a modern format... so please help us add documentation for ebuilds to the wiki!

 

I have created a semantically-enabled directory of ebuilds on the Funtoo Linux wiki, which you can add to and expand. This is going to be the official set of documentation for all our ebuilds. Since we now have a wiki, we have tons more possibility for documenting ebuilds, so let's take advantage of it.

 

I have written up detailed docs on how to add an Ebuild to the wiki, documented here:

 

http://www.funtoo.org/Adding_an_Ebuild_to_the_Wiki

 

This effort is important to help everyone use ebuilds properly, and is also critical for the upcoming QA efforts, so it is an area of great need for the project right now.

 

Best Regards,

 

Daniel

[pytony]

I noticed some ebuilds are documented as http://www.funtoo.org/PkgName instead of http://www.funtoo.org/Package:PkgName (eg. http://www.funtoo.org/Dbus). Some ebuilds are also linked from both schemes (eg. http://www.funtoo.org/Boot-Update and http://www.funtoo.org/Package:Boot-Update ).

 

I guess the prefered URL is http://www.funtoo.org/Package:PkgName. However, what should be done about old URLS? For instance, should I move http://www.funtoo.org/I3_Tiling_Window_Manager to http://www.funtoo.org/Package:I3_(Window_Manager) and add the {{Ebuild}} template? And how do I do a "symlink" from I3_Tiling_Window_Manager as with Boot-Update?

 

Thanks

[666threesixes666]

/pkgname is old scheme prefer package:boot-update especially if there is an ebuild.  some things like iptables need moved to new scheme & old page deleted.  hitting the talk page of the page with request for deletion/migration will bump a recent revision notification on the feed of recently changed pages.

[pytony]

Thank you. By the way, I figured out how to move a page. Still.

[Eduard Nicodei]

I'm going out of a limb here, but reading through the wiki:

 

Our goal for ebuild wiki pages is ambitious -- the wiki should have complete and excellent documentation for using every ebuild in Portage. 

 

Could somebody maybe provide a bit more motivation for having such a goal?

 

On first glance it seems like the request for a lot of duplicated effort. The Gentoo wiki has a lot of documentation and the Arch Linux Wiki is probably one of the best resources for packages of all kind, not to mention the man page (although it is true that some man pages completely lack any depth).

 

Why am I asking this?

Let's take an recent page that was added to the wiki:

http://www.funtoo.org/Package:Tmux

Although max kudos to the person who wrote this, isn't all of the information present on that page already available elsewhere?

 

I completely agree that writing documentation / help is possibly the most important (non code related) contributions to be made to opensource but is such a massive duplication of work necessary? Shouldn't the Funtoo wiki restrict itself to Funtoo-specific changes in the packages?

 

Now I might be horribly wrong here and I apologize for making ignorant claims, but shouldn't there be some clear "Why do we want to do this / Motivation" section in addition to the "Goal" one in http://www.funtoo.org/Adding_an_Ebuild_to_the_Wiki ?

 

[drobbins]

The motivation for this goal is: things should be documented. If things aren't documented, they might as well not exist.

[666threesixes666]

right, were a documentation driven distribution as is arch, gentoo, and linux from scratch...  look at our mediawiki ebuild, i doubt you'll find such an excellent mediawiki cheat sheet anywhere....  why document more than what you have insane tweeks of?  to let people know where to get general info, and all the tweeks they need to know.  i started documenting @ gentoo to address forum posts so i could have a manual to point at when a recurring problem came up, i could repeatedly answer with a link.  instead of 50 thousand threads with hurricanes of chatter going on, you get a concise document, that is incrementally improved.  think of it like forums, but cheat codes of the universe instead of chatter, and filler text.  forums, think of as having to read 30 posts that are not helpful to find 20 useful posts.

 

 

 

https://wiki.archlinux.org/index.php/Mediawiki <--- junky

http://wiki.gentoo.org/wiki/Mediawiki <---- really junky

 

http://www.funtoo.org/Package:MediaWiki#Tips_and_Tricks <---- excellent cheat codes

 

im working on building this:

http://www.funtoo.org/Web-server-stack

 

so that our page can be stack choices agnostic, i can serve mediawiki via lighttpd, nginx + phpfpm, or apache.  right now i only know mysql, but im sure eventually postgresql, mariadb, percona, or what ever else database will be a well documented choice also.

[digifuzzy]

Are we worried about USE flag explanations?

I stumbled on the GentooBrowse site which lists packages, their bugs, use flags, versions et al.

For example GetooBrowse-mediawiki

I'm guessing its the web-version of an equery.

 

I'm just trying to get a sense of how detailed the pages should be.

[drobbins]

No, don't worry about USE except when it comes up for tips/tricks related to successful install. I am automatically importing USE flag descriptions from metadata.xml for forked and overlay ebuilds and hope to add Gentoo ones soon.