[Yum-devel] Updating documentation/man pages
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
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
* 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
>> 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.
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.
I am on London, UK timezone.
More information about the Yum-devel