On Mon, Jan 18, 2010 at 8:04 PM, Seth Vidal <skvi...@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 _______________________________________________ Yum-devel mailing list Yum-devel@lists.baseurl.org http://lists.baseurl.org/mailman/listinfo/yum-devel
