Anaconda Addon Development Guide

[Vratislav Podzimek]

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,

-- 
Vratislav Podzimek

Anaconda Rider | Red Hat, Inc. | Brno - Czech Republic

[Pete Travis]

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(a)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(a)fedoraproject.org

[Leslie S Satenstein]

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(a)yahoo.com
SENT FROM MY OPEN SOURCE LINUX SYSTEM.




> ________________________________
>  From: Pete Travis <me(a)petetravis.com&gt;
> To: For participants of the Documentation Project <docs(a)lists.fedoraproject.org&gt; 
> 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(a)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(a)fedoraproject.org
>
>
>
>
> -- 
> docs mailing list
> docs(a)lists.fedoraproject.org
> To unsubscribe:
> https://admin.fedoraproject.org/mailman/listinfo/docs
>
>

[Vratislav Podzimek]

On Wed, 2014-01-15 at 12:33 -0800, Leslie S Satenstein wrote:
>  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. 
Hi, thanks for the proposed
changes. But the source of the guide is an
XML file and I cannot use the way of applying them you've suggested.
Could you please send a patch for the XML files?

Thanks,

-- 
Vratislav Podzimek

Anaconda Rider | Red Hat, Inc. | Brno - Czech Republic

[Vratislav Podzimek]

On Wed, 2014-01-15 at 09:13 -0700, Pete Travis wrote:
>  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. 
FAS
groups: DONE.
Will have a look at the guide later.

>   
>  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(a)lists.fedoraproject.org . 
DONE.

>   
>  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. 
What can I do for this?
The guide is at:
https://git.fedorahosted.org/cgit/docs/anaconda-addon-development-guide.git/

One more thing I don't understand -- how will it happen that the guide
will appear in the official documentation?

Thanks,

-- 
Vratislav Podzimek

Anaconda Rider | Red Hat, Inc. | Brno - Czech Republic

[Pete Travis]

On Tue, Feb 4, 2014 at 1:44 AM, Vratislav Podzimek <vpodzime(a)redhat.com&gt;wrote:

>  ...
>
>  >
>  > 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.
>  What can I do for this? The guide is at:
>
>  https://git.fedorahosted.org/cgit/docs/anaconda-addon-development-guide.git/
>
>  One more thing I don't understand -- how will it happen that the guide
>  will appear in the official documentation?
>
>  Thanks,
>
>  --
>  Vratislav Podzimek
>
>  Anaconda Rider | Red Hat, Inc. | Brno - Czech Republic
>  
Now that the repo is in place, we should probably create a Transifex
project for it and push POTs for translation.  Much of the tx-client usage
is covered in the Documentation Guide, and the `create-tx-configuration`
package is a big help when creating .tx/config . Ping if you need help, or
would like me to save you some time and set it up for you.

The publishing process is covered in the Documentation Guide, and requires
Publican 2.x as available from Fedora 18.  I still have a box with F18 for
this purpose, and can help if needed.

I would like to work on the formatting a little, and jhradilek expressed an
interest as well ( at least to check my work :) ). Your call on if you want
to publish before or after.

-- Pete