Re: Website Improvement Ideas

[Sascha Wildner <saw@xxxxxxxxx>]

Christopher Rawnsley wrote:
> I have an idea about using man pages and a wiki together. I guess this  
> may have been discussed before but just in case it hasn't... I think  
> it would be great if we could some how integrate the man pages into a  
> wiki like system in order to help keep are documentation as good as  
> possible. But this shouldn't just be a one way thing and the  
> documentation from the wiki should also be exportable back in to the  
> offline man pages in the OS. Thoughts?

Drawing from past experiences with converting the Handbook to Mediawiki 
and thoughts I had at the time, I'm not sure this is worth the trouble.

My impression is that the biggest problem with contributions to manual 
pages (and documentation in general) is not the format or presentation. 
Just open your editor, write, submit. If you're scared of the mdoc 
markup...fine, just submit plain text or whatever your favourite format 
is. I wouldn't care. :)

The real problem is to write good content.

Writing documentation is not easy and manual pages (the system's 
reference manual) in particular should follow some rules and 
restrictions. The style is terse and less is often more. Wikis seem to 
be great for HOWTOs and introductory texts but I'm not convinced if
they'd work well in the manpage case, not to speak of whether changes in 
the Wiki could be conveniently merged back to the manpage.

Of course this is all only my personal opinion.

Sascha

P.S.: And again, if you have manpage content to submit, don't feel held 
back by lack of mdoc knowledge. Any format is OK.

--
http://yoyodyne.ath.cx