There are systems like Sphinx that let you share content between different formats, but they're not magic bullets. For instance, if I write docs relying on inline links because I'm used to viewing them in HTML, the result won't be great for manpage readers.
info () { command info "$@" 2>&1 | less; }
to get the content with a more (or less) familiar nav tool.Another useful approach is to 'project the document' rather than to 'document the project'. Write the draft documents as part of the specification and development process. Code the project. Finally, edit the docs to match the code.
You get to capture the state of early energy and an over- or top-down view before diving into the code, and will remember to mention details of the design while they are fresh and new, rather than at the end of the coding process, when everything has become so familiar that it all seems trivially obvious.
---
SEE ALSO
The full documentation for cp is maintained as a Texinfo manual. If the info and cp programs are properly installed at your site, the command
info coreutils 'cp invocation'
should give you access to the complete manual.---
I ran that 'info' command and promptly ran the one emacs command I have memorized: C-x C-c
:)
I write this up to GNU's "info" being preferred by some programs, but then that not being installed properly or at all on many system, and people hating manpage syntax, often with good reason.
That said, some systems pay a lot of attention to this. OpenBSD's mandoc is a great example of a modernization of the manpage system, and their manpages are second to none: http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html