[ovirt-users] do we need some documentation mainteiners?

[Yedidyah Bar David]

On Thu, May 11, 2017 at 8:50 AM, Yedidyah Bar David <didi at redhat.com> wrote:
> On Wed, May 10, 2017 at 8:07 PM, Juan Pablo <pablo.localhost at gmail.com> wrote:
>> I am!  =)
>> but Im dizzy on how/where to start.
>> suggestions/ideas are welcome
>
> Perhaps start by reading the readme file of the site:
>
> https://github.com/oVirt/ovirt-site
>
> and continue with "CONTRIBUTING.md" and "MAINTAINING.md" there.
>
> If you are new to git/github, you should probably read about them too,
> although for simply editing the web site the basics should be enough.
>
> Feel free to ask any questions - perhaps on devel at ovirt.org instead of
> here. Welcome and good luck!

I'd also like to take the opportunity and talk a bit about the content.

Many times people here refer to RHV documentation.
RHV documentation is indeed very good, but has a few problems, if you
consider "simply" copying from there:

1. It's RHV-specific. 99% of times this is irrelevant, but when it is,
RHV doc writers do not make any attempt to be oVirt-compatible. Examples:
It does not cover at all Fedora-specific issues, it did not cover in the
past use of oVirt 3.5 and 3.6 on EL7 (because RHV did not support that).

2. You should study well the legal notices included in the guides there.
The licenses for RHV documentation are quite different from the licenses
for the oVirt projects' source code.

3. It's written by writers, not developers. This means it's much more
organized, more-or-less complete, better written, but still might be
out-of-date or inaccurate.

4. It tends to be less detailed about feature internals, about things
that might break if you do not follow the doc, about non-standard
potential uses, etc. It's mostly intended for people that do things
"by the book" :-) It usually does not cover things that Red Hat
decided to not support, even if they mostly work.

Other sources for content one should consider, both for direct learning
and as a source for writing documentation:

1. Mailing list archives. Both users and devel can be useful.

2. Discussions on bugzilla bugs. Many times you can find there the most
accurate definition of what a feature does, how to test/use it, and how
it was verified.
When you do that, check if the bug is on oVirt or on RHV. In the past,
the distinction wasn't as accurate and not strictly followed, but in
recent versions we try to better make sure that bugs that are opened
on RHV and affect also oVirt are moved to oVirt. See also:

https://www.ovirt.org/develop/dev-process/bugzilla-rework/

3. Source code. In some parts it's rather easy to follow if you have
any experience dealing with source code, and in others you can at least
read the comments. This applies even if you never _wrote_ a single line
of source code in any programming language. when you decide to have a
look at the source code, you should do this by cloning the git projects,
not by downloading the tarballs or SRPMs. This way you win on two fronts:
a. You get at once the entire project history including all its versions,
in a single place.
b. You can then also search the git history and find out when something
was changed, comments about the change, etc.

4. gerrit. gerrit is our review tool, and all patches for the projects
maintained there go through it. This in many cases includes long
discussions between developers about what the patch actually should
do and how it should do that. In some cases you can also see there how
a patch was verified to do what it's supposed to do.
Sadly, gerrit review history isn't as easy to search as the other
sources above. Perhaps we should do something to make it easier as well.

>
>>
>> JP
>>
>> El 10/5/2017 12:20, "Barak Korren" <bkorren at redhat.com> escribió:
>>>
>>> On 10 May 2017 at 14:18, Juan Pablo <pablo.localhost at gmail.com> wrote:
>>> > this was not the intention of the thread. so please stop throwing
>>> > bananas
>>> > each other.
>>> >
>>> > Lets focus on the subject here:do we need some documentation
>>> > mainteiners?
>>> > yes/no
>>>
>>> My answer would be definitely.
>>> If you are volunteering, you would be very welcome.
>>>
>>>
>>> --
>>> Barak Korren
>>> RHV DevOps team , RHCE, RHCi
>>> Red Hat EMEA
>>> redhat.com | TRIED. TESTED. TRUSTED. | redhat.com/trusted
>>
>>
>> _______________________________________________
>> Users mailing list
>> Users at ovirt.org
>> http://lists.ovirt.org/mailman/listinfo/users
>>
>
>
>
> --
> Didi



-- 
Didi