Anaconda Addon Development Guide

Wed Jan 15 20:33:51 UTC 2014

May I offer some corrections or modifications to the draft document.  I feel that it is very good as is, but needs some editing.  I will paste my comments in line with colored text for page 1.

I propose to use libreOffice edit->change> as the markup and comment tool.  Using this tool, a group of individuals can work on a common document and be able to collaborate on it. 

Given I work in
French, Spanish and I arrived at those languages later in life, I
would like to offer my experience to the author(s).  It is important
to realize that many times the text will be read by a non English
speaking person, who has English knowledge.  My feedback is based on
wearing a foreign language hat and reading the English.  I marked the
changes in yellow or recommended changes in yellow, followed with
comments.

Please add an introductory paragraph
stating that the target audience for this article is the system
maintainer. It is to provide information to assist the system
maintainer to tailor Anaconda to his requirements.

 Anaconda is the operating system installer (OS) used in Fedora, RHEL
and their derivatives. At a closer look, it is a set of Python
modules and scripts together with some additional files like Gtk
widgets (written in C), systemd units and dracut libraries. Altogether they form a tool that
allows users to set parameters of the resulting (target) system and
then set such a system up on a machine. The final installation
process has four major steps: 

Could you rephrase
this slightly so that a non English person can mentally translate the
English to his mother tongue has an easier time?  May I suggest

Altogether
they form a tool that allows users to establishparameters for the resulting (target) system and then install such a
system ontoa machine. 

=== 
 There are three ways the user can set parameters for the target
system (and in some cases also for the installation process). The
most commonly used way is via the graphical user interface (GUI)
which should cover all common use cases and should be clear and
easily understandable even for non-advanced users. 

Paragraph break
 Although Anaconda also supports
installation over VNC , there are some corner cases where a textual
interface is needed, such as installation over serial console on
"exotic" pieces of hardware. For
this reason, Anaconda also has a textual user interface (TUI) that
works the same way as a black-only line printer. This behavior
was chosen as a result of various serial consoles not supporting
cursor movement, colors and other "advanced" features. Text
mode installation implements only the most important features of the
graphical installation and usually needs to be combined with
installer-specific command line arguments since it does not provide
all of the options the GUI provides. 

Paragraph break
 The third and most advanced way to set installation parameters is by
using a kickstart file. This is a simple file with shell-like syntax
which can contain data driving the installation process, which then
runs automatically. If the kickstart file doesn't contain all data
required, the installer asks the user about the missing pieces. More
information about kickstart can be found at the
Anaconda/Kickstart wiki page. Addons related kickstart
specifications are covered in Section 5,
“Addon structure”. The important distinction to note is that,
compared to the TUI, which is not a full-featured mode of
installation, kickstart installation provides the highest number of
configuration options. The golden rule is that everything has to be
supported in kickstart first. Then the GUI and TUI pieces can follow,
supporting subsets of configuration options provided in kickstart
that allow the user interface (UI) to remain clear and succinct.
Anaconda has to maintain a balance between simplicity and complexity
which is difficult to achieve. 

The above highlighted sentence is a bit too long. I touched it up as
follows:
The most commonly used way is via
the graphical user interface (GUI). This
choiceshould cover all
common use cases and should be clear and easily understandable, even
for non-advanced users.
The following sentence has
slang.
 Although Anaconda also supports
installation over VNC , there are some corner cases where a textual
interface is needed, such as installation over serial console on
"exotic" pieces of hardware.

I touched it up as follows:
 Although Anaconda also supports
installation over VNC , there are some exceptional cases where a textual interface is needed, such as installation via serial console onto"exotic" pieces of hardware.

In the following, sentence,
what is a black-only line printer?  Do you mean as a display
on a tty terminal?
 For
this reason, Anaconda also has a textual user interface (TUI) that
works the same way as a black-only line printer.

Reshuffle this text
Text mode installation
implements only the most important features of the graphical
installation and usually needs to be combined with installer-specific
command line arguments since it does not provide all of the options
the GUI provides.

To this

Since it does not provide all
of the options the GUI provides, text mode installation implements
only the most important features of the graphical installation and
usually needs to be combined with installer-specific command line
arguments.  

On a follow up document, I
propose to use the LibreOffice markup facility (Edit »Changes »
Record)

Should I proceed?  

Regards 

 Leslie

Mr. Leslie Satenstein
An experienced Information Technology specialist.
Yesterday was a good day, today is a better day,
and tomorrow will be even better.lsatenstein at yahoo.com
SENT FROM MY OPEN SOURCE LINUX SYSTEM.

>________________________________
> From: Pete Travis <me at petetravis.com>
>To: For participants of the Documentation Project <docs at lists.fedoraproject.org> 
>Sent: Wednesday, January 15, 2014 11:13 AM
>Subject: Re: Anaconda Addon Development Guide
> 
>
>On 01/15/2014 04:53 AM, Vratislav Podzimek wrote:
>
>> Hello everybody,
>> my name is Vratislav Podzimek and I am a member of the Anaconda
>> installer team. The Anaconda installer now supports third-party
>> extensions called addons and I have written a guide for implementation,
>> deployment and testing of such addon.
>>
>> Now I would like this guide to be included as part of the official
>> Fedora project documentation suite. Could anyone please tell me which
>> steps are needed for that to happen?
>>
>> The guide is here:
>> http://vpodzime.fedorapeople.org/anaconda-addon-development-guide/
>>
>> with the sources here:
>> https://github.com/vpodzime/anaconda-addon-development-guide
>>
>> Thanks,
>>
>Hi Vratislav!  This guide looks very interesting, and it is great that
>you would like to share it with us. Thanks!
>
>Our path here should be this:
>1.a We need to get you into the appropriate docs FAS groups. General
>membership is in "docs", general commit access in "docs-writers", and
>publishing access in "docs-publishers". As a guide owner and experienced
>writer, I'm comfortable sponsoring you for all three. Tell us your FAS
>ID so we can sponsor you - and use your powers wisely :)
>1.b - Many of the Fedora Docs processes are detailed in our
>Documentation Guide[1].  It has been a work in progress for some time,
>but still helpful.  That is a polite way of saying that it *really needs
>a refresh*.  It would be a big help if you could reference the version
>in git[1] instead of at docs.fp.o.  If you find something missing,
>confusing, outdated, or incorrect you can fix it or just complain in a
>bug or mail - your perspective as a new participant is valuable feedback.
>
>2. Open a trac ticket[2] with infra for a fedorahosted git repo and
>bugzilla component to be created for the guide. Skip the git portion of
>the wiki page; once the new repo is available, I *think* you should be
>able to just `git remote add foo` and push to fedorahosted. The ticket
>should also specify that commit traffic go to
>docs-commits at lists.fedoraproject.org .
>
>3.  Once the content is in a shared space, we can do some peer review. 
>Your content looks great, and we have some very experienced technical
>writers that can help improve presentation and structure.
>
>4.  After review, set up a Project for the guide on Transifex so that
>Fedora's l10n team can translate it.  The source language needs to be
>en-US and iirc someone needs to add the new project to the Fedora
>organization.  We can go over the details on this when the time comes.
>
>5.  Optionally, you could create a wiki page to guide potential
>contributors to your Guide. You could them know what you plan to work
>on, where you would like help, where you don't want the scope to creep
>to, or how to contact you to plan new sections.
>
>6.  Keep in touch! There are docs people around the world and clock that
>can help you on your way. You can find us here on the list, or in
>#fedora-docs .
>
>[1] https://git.fedorahosted.org/cgit/docs/documentation-guide.git
>[2] https://fedoraproject.org/wiki/Creating_a_new_guide
>
>-- 
>-- Pete Travis
>- Fedora Docs Project Leader
>- 'randomuser' on freenode
>- immanetize at fedoraproject.org
>
>
>
>
>-- 
>docs mailing list
>docs at lists.fedoraproject.org
>To unsubscribe:
>https://admin.fedoraproject.org/mailman/listinfo/docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20140115/8a90f974/attachment-0003.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: anacondaLeslie.odt
Type: application/vnd.oasis.opendocument.text
Size: 29638 bytes
Desc: not available
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20140115/8a90f974/attachment-0003.odt>