DragonFly users List (threaded) for 2008-04
Re: Website Improvement Ideas
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.