Documentation WAS: pkg question ....

[Polytropon]

On Wed, 6 Aug 2014 22:48:30 -0600 (MDT), Warren Block wrote:
> On Wed, 6 Aug 2014, Paul Kraus wrote:
> 
> > I understand that developers want to develop and not write manuals.
> 
> Documentation should be seen as part of developing.  It is not an 
> optional extra.  A program without documents is incomplete.

Traditional understanding of "development" (traditional term:
"programming") contains more than just _coding_. As you said,
documentation is an essential part, but so is planning, testing,
debugging - nobody would disagree. Today's "modern" understanding
of "app dev" probably focuses on coding, marketing, and raising
money by the billions. :-)

Documentation isn't just manpages. It's also useful (!) comments
in the code, and the code also is documentation. It's READMEs,
comment headers, and other files that are easy to locate and
read. Required skills are: language, reading, writing, thinking.
And: No, those are not "common knowledge" anymore. :-(

As with all aspects of development, writing documentation costs
time, and because "time is money", money. But it's a very good
investment in usability, sustainability, and success of software.
It's just that you don't get a 100x return the next day.



> Documentation does not have to be perfect, any more than the program 
> itself.  But it should answer the basic questions:
> 
> What is this?
> What are the requirements?
> How is it used?
> 
> In that last part: good, useful examples can make the difference between 
> a successful application and one that is abandoned because people can't 
> figure out how make it work.

This is actually very important. From my (very individual) point
of view as a developer, I can say that I've seen myself "doing it
wrong" several times: a script that does something important and
clever, but not even a comment header about what it exactly does
and how it should be configured and invoked. :-)

Regarding manpages: They are a reference manual, not a user's manual
covering _all_ parts of the software, which whould make them too
huge, especially in regards of GUI programs. But the few aspects
you've mentioned should be covered; "man opera" is a good example:
it's not an "entire heap of all the documentation", but it states
what the program is, what command line options it provides, and how
it can be configured. Everything else is found in the online help
system. This is better than nothing (compare "man firefox").

Software without documentation is fine as long as it works
(and you're not interested in how or why it works). As soon
as problems arise, you are happy about any documentation that
you can easily access, even if you have to work under the worst
imaginable circumstances (no Internet, only text mode access).
I don't say this happens all the time, but at least it happens.
That's something I can say from my own experience.



> Finally, FreeBSD developers and users should be aware that the FreeBSD 
> documentation team can provide assistance with creating man pages or 
> DocBook documentation like the Handbook.  People interested in that help 
> can post on the freebsd-doc mailing list.

The OS installation itself provides templates for manpages of
different sections, as well as the sources for the DocBook kind
of documentation which itself is well documented and makes it
easy to derive your own documentation.



-- 
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...