Gentoo Developers Video Library

Well, this comes rather longer and bigger than I anticipated.

Now, getting to a suggestion I was trying to work out for resolving boring documentation issues. So, I have to thank few people first, and they all are our great User Representatives:

Loki99 - his views (rather pessimistic this time) help me concentrate and recheck myself.

Now, although I did came up with initial thoughts for this, it was developed, checked, edited, added ideas and contributed in sorts of other different ways by Q-collective and toskala. Thanks guys.

After reading a lot about Ebuild GUI builder (tm) and even contributing my cents to the debate, I got few responds to my writing. In general, responses can be summarized by the following:

1. I totally agree with you! Can I quote you in my prayers?

2. In general, I agree with what you said, but even creating a simple ebuild automatically can be something not as generic as it sounds. It can be even wrong in some cases to ignore USE flags, because installing a package with default procedure (./configure; make; make install) can be incorrect and sometimes even break something in the system.

Besides that, everyone seems to agree with me though, that users should read a portage documentation (which potentially can provide Gentoo with more developers in the future).

But then, we get back to the original question: “Why would users want a GUI builder for ebuilds?”

I believe there are 2 reasons for that:

1. For an occasional user, it would save time for creating a “simple” ebuild - as all he or she has to do is (supposedly) provide some basic details about the package he/she would like to build and automagically an ebuild would be built for her.

2. No one wants to read the documentation. Don't get me wrong on this - I know what the documentation is for and the reasons for it to be read, but for someone who wants something done fast (and in lots of cases this would be a one-time contributing user) - reading lots of stuff even before getting to the point is a definite intention killer.

So, after I thought about it, I understand the issue and agree, that the first action item (creating an automatic ebuilds builder) cannot be solved easily - or fast for that matter.

But documentation and an attitude towards it might be.

So, if I would to redefine the problem, I'd say it's this:

"Gentoo [developer] documentation (which provides an information and knowledge about portage and ebuilds) is an especially boring read for one-timers. What we need, is one of the following: allow creating an ebuild with less effort that it requires today or make a process of getting the information about it more interesting".

So, I have a suggestion about making it more interesting.

I would call it "Hands-on developers library".

The concept I propose is as following: create a screen-cast (video-cast, screen recording - choose an appropriate name) of actual writing of an ebuild (using your favorite text editor). Make it only few minutes long. Add audio comments to it and explain at each step what is it that you do. Redirect for more info to the documentation and give the direct links to it.

Rationale

I believe, that following benefits can be achieved by such information representation:

1. Watching “movies” is much more fun than reading plain documentation. Specifically, while keeping them small enough, this kind of movies provides a user in minutes with concentrated needed information she needs, so she can start “experimenting” creating her own ebuilds immediately.
2. By giving an example of writing a simple ebuild, you could inspire users to follow given directions to create their own ebuild. They would hear explanations for each step, so they will better understand what even simplest things are there for. They will also see the redirection to a full documentation site, so there won't be a need to go over piles of docs to find the specific one they are looking for.
3. If needed more complex example with more complex ebuilds, make another recording. Just keep it short enough not to get a boring school lecture.
4. It is possible to create as many recordings as would be found fit.
5. Such examples can be developed in parallel by several people, thus multiplying the amount of examples and easily expanding the experiences in the library.

In addition, I find that the following issues should be addressed:

Relation to "may never come to existence" Ebuilds GUI builder.

Such implementation has no direct relation to a EGB (Ebuilds GUI builder). It just tries to solve a particular problem by other way.

License

I believe, that if implemented, such recordings should be released under an opened license. As such, CC (Creative Commons), which used widely for creative content, may be appropriate.

Technology

Few aspects of technology should be worked out, such as:

• Format in which these recordings would be created.
• Tagging, indexing, creating chapters for easier and later access and search of content.
• Storing the content of each recording (ebuild) online in ASCII form, so easy content usage can be allowed for later personal use and experimentation.
• Minimal requirements for a system where one should be able to see those recordings (depends on a format chosen).

An example of interactive chapters approach is the use of flash technology (although it is known not to be much loved inside the community). Other solution can be a real movie file (in formats such as MPEG or OGG).

Accessibility

This aspect of the project should get attention as well. By accessibility I mean allowing blind and hearing-impaired people to enjoy the fruits of this project:

• Transcription of voice recording, which would show as subtitles in timely matter.
• Creating full audio of a particular recording should be technically supported.

Styling

Our aspiration for quality requires all content to be as professional or at least as consistent as possible. This requires for "styling guidelines" to be developed, which would include some, all or at least the following:

• Fonts chosen.
• Fonts sizes.
• Color schemes.
• Speaker with a nice and easily understandable voice.

Medium of distribution

An appropriate medium should be chosen. Whether it will be hosted by Gentoo or by, for example, Google or YouTube remains to be decided. It is also very dependent on format chosen for recordings.

Security

Because such recordings actually show how to create an ebuild, there's a risk that "faulty" and erroneous recordings (which if followed could destroy the system) may appear in the web. To fight off such security issue, few things should be resolved:

• Authorization and authentication processes by official Gentoo should take place. For example, only recordings which are hosted by Gentoo are authentic.
• Even today, such an ebuild can be introduced into bugzilla, and as such can be probably related as similar threat. Such ebuild in bugzilla (or recordings) would probably get a comment that it contains negative content, and their distribution would slow down.

Anyhow, the matter of security on such sensitive subject should not be taken lightly.

Pro's and con's

Technologies

• Choosing flash format would allow interactive menus/chapters/links, but it is a closed format, and as such may not be chosen.
• Creating chapters/index/live links inside the recordings would complicate the creation process but make it easier to access the content later.

Distribution Medium

• Choosing to host recordings on Gentoo would allow easier authentication and authorization of the content.
• Choosing to host recordings on Google Video or YouTube would save a lot of bandwidth and hence lower the costs, but may create a “security hole” as not being “authenticated”.

Licensing

• Choosing CC over other types of license, makes the process easier as CC was specifically created for licensing creative content as audio, video, pictures and text.

Styling

• Choosing to work in particular style may complicate a bit and prolong the process of creating a recording, but in doing so, it will make easier to impaired to understand the content.

I also believe that such recordings would make Gentoo even more unique than it is today.

In addition, this may allow us to kick ass Debian, Ubuntu, Fedora, SUSE, Mandrake or whatever!

Few more things:

1. I don't believe in miracles made by humans. I don't think that from the first recording everything will be perfect. It can be started with something small, and get developed over time to answer all the issues mentioned earlier.
2. This suggestion does not nullify reading the documentation. It is merely a step which tries to simplify the process of initial understanding how portage works and how to create packages. For serious portage/ebuild development one would still have to go through a lots of documentation, tests, quizzes, mentoring and whats not.
3. I think this can be good idea for the UserRep project, as it will allow correlating between what users need and what developers can provide them with.
4. Although this may get more users to try and develop something for Gentoo (and that would be great if it happens), it doesn't mean that reading documentation later would be less boring and less abstract.

Thats about it. Comment it or not, its a completely your choice.