Date: Thu, 7 Aug 2014 07:16:18 +0200 From: Polytropon <freebsd@edvax.de> To: Warren Block <wblock@wonkity.com> Cc: FreeBSD Questions !!!! <freebsd-questions@freebsd.org> Subject: Re: Documentation WAS: pkg question .... Message-ID: <20140807071618.11dc548a.freebsd@edvax.de> In-Reply-To: <alpine.BSF.2.11.1408062223080.94639@wonkity.com> References: <53E0D2B7.9060402@hiwaay.net> <20140805131910.GA72939@slackbox.erewhon.home> <53E0E281.9030306@hiwaay.net> <20140805225107.ccf9944a.freebsd@edvax.de> <10FF0A4F-F96E-4A68-BA25-56B57AFD4B2E@kraus-haus.org> <alpine.BSF.2.11.1408062223080.94639@wonkity.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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, ...
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20140807071618.11dc548a.freebsd>