Lines Matching full:documentation
5 perldocstyle - A style guide for writing Perl's documentation
10 documentation that ships with Perl. This includes the following:
21 The documentation for all the modules included with Perl (as listed by
37 applicable to Perl's core documentation.
41 with the rest of the Perl project, the language's documentation
48 more welcome and engaged with Perl's documentation, and this in turn
54 Anyone interested in contributing to Perl's core documentation should
64 documentation style guides of several open-source technologies
69 which to launch a review of Perl's reams of extant documentation, with
78 All of Perl's core documentation uses Pod ("Plain Old Documentation"), a
95 Perl's core documentation is written in English, with a preference for
101 documentation, much as a software project might declare a four-space
106 Contributors to Perl's documentation should note that this rule
109 documentation team enthusiastically welcomes any English-language
115 Community-authored translations of Perl's documentation do exist,
120 That said, keeping Perl's documentation clear, simple, and short has a
130 Perl's core documentation files are encoded in UTF-8, and can make use
138 Perl's documentation uses the L<Chicago Manual of
146 for contributing to Perl's documentation; the doc team will help
153 =head2 Contributing to Perl's documentation
156 documentation. Perl depends upon clear, friendly, and thorough
157 documentation in order to welcome brand-new users, teach and explain the
161 documentation.
163 Perl accepts documentation contributions through the same open-source
170 documentation should adhere to, in the interest of consistency and
175 Each individual work of core Perl documentation, whether contained
179 self-contained part of Perl's documentation.)
235 L<suggested elsewhere in this guide|/Apply one of the four documentation
251 documentation|/The documentation speaks with one voice>.
323 documentation:
365 documentation|perlfunc/substr>, whose
384 (outside of Perl's documentation), include its manual section number in
402 documentation. Generally, the first time you refer to a specific
404 linking to its full documentation.
410 link to its documentation section within the C<perlfunc> man page:
455 nor diagrams. Like any other tool in your documentation toolkit,
479 someone reading the documentation through normal means, so it's
481 fellow documentation writers.
486 but judicious use of comments to leave in-line "meta-documentation" as
487 needed for other Perl documentation writers (including your future
494 elsewhere in Perl's documentation.
570 =head2 Apply one of the four documentation modes
572 Aside from "meta" documentation such as C<perlhist> or C<perlartistic>,
573 each of Perl's man pages should conform to one of the four documentation
574 "modes" suggested by L<I<The Documentation System> by Daniele
575 Procida|https://documentation.divio.com>. These include tutorials,
579 Each mode of documentation speaks to a different audience--not just
581 whose needs from language documentation can shift depending upon
589 Perl's documentation must strive to meet these different situational
591 writers ensure they provide readers with the documentation needed or
643 (An aside: I<The Documentation System> calls this mode "how-to", but
657 into Perl, with each function's documentation presenting the same kinds
661 Module documentation--including that of all the modules listed in
688 the remainder of this guide discusses, the ideal Perl documentation
692 =head3 Further notes on documentation modes
705 man page, or (in the case of module documentation) making new packages
707 documentation. For instance, C<Example::Module>'s reference documentation
723 Perl's core documentation must recognize this by making as few
725 should assume that readers of Perl's documentation are smart, curious,
730 =head3 Keep Perl's documentation about Perl
733 with other programming languages, the documentation should keep the
749 mention that link after its more immediately useful documentation.
751 documentation or external articles more concerned with examining Perl's
756 Domain-specific jargon has its place, especially within documentation.
762 appears throughout its documentation. A new Perl programmer arriving at
766 elsewhere in Perl's documentation. If appropriate--for example, in the
777 permanent documentation, however, can and should make an effort to
795 documentation's language for the sake of internal consistency, authors
798 As much as possible, the language employed by Perl's core documentation
805 "second-order" documentation about Perl, like books, blog entries, and
812 Placeholder text does not belong in the documentation that ships with
822 which do not help readers at all today--the documentation's
823 maintenance team should treat any known documentation absences as an
827 documentation as undeleted debug messages do in production code.
832 text in technical documentation can present a will-weakening challenge
838 plenty of subsections in your documentation lets other man pages more
844 Among the four documentation modes, sections belong more naturally in
851 of documentation. Code blocks help break up a man page visually,
867 many avenues for, the documentation should always lead with best
875 file for reading or writing. For this reason, C<open>'s documentation
879 C<open> documentation does not burden the reader right away with detailed
885 Sometimes, thoroughness demands documentation of deprecated techniques.
889 code. In this case, these features deserve documentation, but couched in
895 Python's documentation team) involves writing while sympathizing with a
897 concept. By leading that concept's main documentation with clear,
907 Perl's documentation should stay focused on Perl's present behavior,
918 When some Perl feature changes its behavior, documentation about
923 Since Perl's core documentation is part of Perl's source distribution,
943 pragma--deserve documentation, but only in certain contexts, and even
947 The documentation should take both implications of "experimental"
961 documentation that L<puts best practices first|/Lead with common cases
964 =head2 The documentation speaks with one voice
967 the many years of Perl's lifetime, the language's documentation should
975 documentation as well. Today, Perl's community understands that the
978 documentation should not pretend otherwise.
980 The documentation should, however, carry forward the best tradition that
984 the dryness that one might expect from technical documentation, while
988 Like the best written works, Perl's documentation has a soul. Get
1007 to Perl documentation.
1029 One unit of Unix-style documentation. Not "manpage". Preferable to "manual page".
1046 Documentation need not follow Perl's name with a "5", or any other
1078 Perl. As such, Perl's documentation should always refer to this language