DragonFly users List (threaded) for 2008-04
DragonFly BSD
DragonFly users List (threaded) for 2008-04
[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]

Re: Website Improvement Ideas

From: Sascha Wildner <saw@xxxxxxxxx>
Date: Mon, 21 Apr 2008 21:58:44 +0200

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.


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.


[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]