[Yum-devel] Updating documentation/man pages

Gerhardus Geldenhuis gerhardus.geldenhuis at gmail.com
Mon Jan 18 22:19:05 UTC 2010


On Mon, Jan 18, 2010 at 8:04 PM, Seth Vidal <skvidal at fedoraproject.org> wrote:
>>
>> Changes I want to make:
>> * Write a layout and style convention guide for yum and related tools
>> man pages( subject to list review of course )
>
> This one doesn't do much for me - but if you think it'll get people to
> actually READ the docs - then sure.

If only it were that easy to get people to read docs... my motivation
is to create consistency and predictability. I don't envisage much
changing and it was more for my own benefit as a guideline to follow
when I go through the documentation. If I only edit things that
catches my fancy then I am not being thorough nor am I improving the
documentation.

Things I had in mind for example is:
* the consistent use of hypens, minus and dash characters.
* "correct" use of capitalization. ( I use the term correct loosely )
* consistent spelling, I favour consistency whether it is British or
American spelling.
* Breaking up lengthy sentences.

>
>> * Ensure that style guide is compatible in terms of rendering on all
>> major platforms where yum is used.
>
> you mean linux, linux, and linux? That's  all I can think of.

hmmm, my expectancy was that different man versions or troff/groff
combinations might be used in various distributions. Its easy enough
to check but if not then you are probably right, one size fits all. I
do think it should look good at 80 margin and anything wider

>> Any thoughts on keeping documentation in a different format and
>> "generating" specific formated documentation of which man is only one
>> type. Other types could be info pages. Personally I am not a big fan
>> of info pages, man works well and the migration from man to info seem
>> to have got stuck...
>
> I never use info pages unless i'm FORCED to do so and I don't much see the
> point in converting out of man pages.

Cool we are agreed on this point, I much prefer man pages myself too.
What I meant by a "different" format was something like docbook. I
also don't know if there is any auto document generation from the
code.

>
>
>> Lastly will there be any objections in me using trac to manage the
>> document changes?
>
> <shrug> If you want to use git to manage the document changes there is a
> yum-docs git tree that has gone unloved for quite a while.
>
>
> http://yum.baseurl.org/gitweb?p=yum-docs.git;a=summary

I will browse through that tree a bit.

My intent in using trac was to log "bugs" in the documentation to to
make sure that they get looked at. I want to define the "work needed"
in trac and keep the source and changes in git.

Btw,
I am on London, UK timezone.

Regards

-- 
Gerhardus Geldenhuis


More information about the Yum-devel mailing list