<!-- header_tag -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Copyright C 1999-2008 by the authors
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
-->
<!-- Created on January 20, 2009 by texi2html 1.79
texi2html was written by:
Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>GNU LilyPond Contributor's Guide: 3.1 Introduction to documentation work</title>
<meta name="description" content="GNU LilyPond Contributor's Guide: 3.1 Introduction to documentation work">
<meta name="keywords" content="GNU LilyPond Contributor's Guide: 3.1 Introduction to documentation work">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.79">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#index" rel="start" title="GNU LilyPond — Contributor's Guide">
<link href="index_toc.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index_abt.html#SEC_About" rel="help" title="About This Document">
<link href="Documentation-work.html#Documentation-work" rel="up" title="3. Documentation work">
<link href="Major-release-checklist.html#Major-release-checklist" rel="next" title="8.3 Major release checklist">
<link href="Documentation-work.html#Documentation-work" rel="previous" title="3. Documentation work">
<link rel="stylesheet" type="text/css" title="Patrick McCarty's design" href="lilypond-mccarty.css">
<link rel="alternate stylesheet" type="text/css" href="lilypond.css" title="Andrew Hawryluk's design">
<link rel="alternate stylesheet" type="text/css" href="lilypond-blue.css" title="Kurt Kroon's blue design">
<!--[if lte IE 7]>
<link href="lilypond-ie-fixes.css" rel="stylesheet" type="text/css">
<![endif]-->
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<div id="main">
<a name="Introduction-to-documentation-work"></a>
<table class="nav_table">
<tr><td valign="middle" align="left" colspan="1">[<a href="Documentation-work.html#Documentation-work" title="Beginning of this chapter or previous chapter"> << Documentation work </a>]</td><td valign="middle" align="center" colspan="3">[<a href="index.html#index" title="Cover (top) of document" rel="start">Top</a>][<a href="index_toc.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][Index][<a href="index_abt.html#SEC_About" title="About (help)" rel="help"> ? </a>]</td><td valign="middle" align="right" colspan="1">[<a href="Website-work.html#Website-work" title="Next chapter"> Website work >> </a>]</td></tr><tr><td valign="middle" align="left" colspan="2">[<a href="Documentation-work.html#Documentation-work" title="Previous section in reading order" accesskey="p" rel="previous"> < Documentation work </a>]</td><td valign="middle" align="center" colspan="1">[<a href="Documentation-work.html#Documentation-work" title="Up section" accesskey="u" rel="up"> Up : Documentation work </a>]</td><td valign="middle" align="right" colspan="2">[<a href="Texinfo-crash-course.html#Texinfo-crash-course" title="Next section in reading order" accesskey="n" rel="next"> Texinfo crash course > </a>]</td></tr></table>
<a name="Introduction-to-documentation-work"></a>
<h2 class="section">3.1 Introduction to documentation work</h2>
<p>Our documentation tries to adhere to our <a href="Documentation-policy.html#Documentation-policy">Documentation policy</a>. This policy contains a few items which may seem odd.
One policy in particular is often questioned by potential
contributors: we do not repeat material in the Notation Reference,
and instead provide links to the “definitive” presentation of
that information. Some people point out, with good reason, that
this makes the documentation harder to read. If we repeated
certain information in relevant places, readers would be less
likely to miss that information.
</p>
<p>That reasoning is sound, but we have two counter-arguments.
First, the Notation Reference – one of <em>five</em> manuals for
users to read – is already over 500 pages long. If we repeated
material, we could easily exceed 1000 pages! Second, and much
more importantly, LilyPond is an evolving project. New features
are added, bugs are fixed, and bugs are discovered and documented.
If features are discussed in multiple places, the documentation
team must find every instance. Since the manual is so large, it
is impossible for one person to have the location of every piece
of information memorized, so any attempt to update the
documentation will invariably omit a few places. This second
concern is not at all theoretical; the documentation used to be
plagued with inconsistent information.
</p>
<p>If the documentation were targeted for a specific version – say,
LilyPond 2.10.5 – and we had unlimited resources to spend on
documentation, then we could avoid this second problem. But since
LilyPond evolves (and that is a very good thing!), and since we
have quite limited resources, this policy remains in place.
</p>
<p>A few other policies (such as not permitting the use of tweaks in
the main portion of NR 1+2) may also seem counter-intuitive, but
they also stem from attempting to find the most effective use of
limited documentation help.
</p>
<hr size="6">
<table class="nav_table">
<tr><td valign="middle" align="left" colspan="1">[<a href="Documentation-work.html#Documentation-work" title="Beginning of this chapter or previous chapter"> << Documentation work </a>]</td><td valign="middle" align="center" colspan="3">[<a href="index.html#index" title="Cover (top) of document" rel="start">Top</a>][<a href="index_toc.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][Index][<a href="index_abt.html#SEC_About" title="About (help)" rel="help"> ? </a>]</td><td valign="middle" align="right" colspan="1">[<a href="Website-work.html#Website-work" title="Next chapter"> Website work >> </a>]</td></tr><tr><td valign="middle" align="left" colspan="2">[<a href="Documentation-work.html#Documentation-work" title="Previous section in reading order" accesskey="p" rel="previous"> < Documentation work </a>]</td><td valign="middle" align="center" colspan="1">[<a href="Documentation-work.html#Documentation-work" title="Up section" accesskey="u" rel="up"> Up : Documentation work </a>]</td><td valign="middle" align="right" colspan="2">[<a href="Texinfo-crash-course.html#Texinfo-crash-course" title="Next section in reading order" accesskey="n" rel="next"> Texinfo crash course > </a>]</td></tr></table>
<!-- footer_tag -->
<div class="footer">
<p class="footer_version">
This page is for LilyPond-2.12.2 (stable-branch).
</p>
<p class="footer_report">
Your <a href="http://lilypond.org/web/devel/participating/documentation-adding">suggestions for the documentation</a> are welcome, please report errors to our <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">bug list</a>.
</p>
</div>
<!-- FOOTER -->
<!-- end div#main here -->
</div>
<div id="tocframe">
<p class="toc_uplink"><a href="../index.html"
title="Documentation Index"><< Back to Documentation Index</a></p>
<h4 class="toc_header"> <a href="index.html#index" title="Start of the manual">Contributor’s Guide</a></h4>
<div class="contents">
<ul class="toc">
<li><a name="toc-Starting-with-git-1" href="Starting-with-git.html#Starting-with-git">1. Starting with git</a>
<ul class="toc">
<li><a name="toc-Getting-the-source-code-1" href="Getting-the-source-code.html#Getting-the-source-code">1.1 Getting the source code</a> </li>
<li><a name="toc-Updating-the-source-code-1" href="Updating-the-source-code.html#Updating-the-source-code">1.2 Updating the source code</a> </li>
<li><a name="toc-Sharing-your-changes-1" href="Sharing-your-changes.html#Sharing-your-changes">1.3 Sharing your changes</a> </li>
<li><a name="toc-Other-interesting-Git-commands-1" href="Other-interesting-Git-commands.html#Other-interesting-Git-commands">1.4 Other interesting Git commands</a> </li>
<li><a name="toc-Git-on-Windows-1" href="Git-on-Windows.html#Git-on-Windows">1.5 Git on Windows</a> </li>
</ul>
</li>
<li><a name="toc-Compiling-1" href="Compiling.html#Compiling">2. Compiling</a>
<ul class="toc">
<li><a name="toc-move-AU-1-here-1" href="move-AU-1-here.html#move-AU-1-here">2.1 move AU 1 here</a> </li>
</ul>
</li>
<li class="toc_current"><a name="toc-Documentation-work-1" href="Documentation-work.html#Documentation-work">3. Documentation work</a>
<ul class="toc">
<li class="toc_current"><a name="toc-Introduction-to-documentation-work-1" href="Introduction-to-documentation-work.html#Introduction-to-documentation-work">3.1 Introduction to documentation work</a> </li>
<li><a name="toc-Texinfo-crash-course-1" href="Texinfo-crash-course.html#Texinfo-crash-course">3.2 Texinfo crash course</a> </li>
<li><a name="toc-Documentation-policy-1" href="Documentation-policy.html#Documentation-policy">3.3 Documentation policy</a> </li>
<li><a name="toc-Tips-for-writing-docs-1" href="Tips-for-writing-docs.html#Tips-for-writing-docs">3.4 Tips for writing docs</a> </li>
<li><a name="toc-Updating-doc-with-convert_002dly" href="Updating-docs-with-convert_002dly.html#Updating-docs-with-convert_002dly">3.5 Updating doc with convert-ly</a> </li>
<li><a name="toc-Translating-the-documentation-1" href="Translating-the-documentation.html#Translating-the-documentation">3.6 Translating the documentation</a> </li>
</ul>
</li>
<li><a name="toc-Website-work-1" href="Website-work.html#Website-work">4. Website work</a>
<ul class="toc">
<li><a name="toc-Introduction-to-website-work-1" href="Introduction-to-website-work.html#Introduction-to-website-work">4.1 Introduction to website work</a> </li>
<li><a name="toc-Translating-the-website-1" href="Translating-the-website.html#Translating-the-website">4.2 Translating the website</a> </li>
</ul>
</li>
<li><a name="toc-LSR-work-1" href="LSR-work.html#LSR-work">5. LSR work</a>
<ul class="toc">
<li><a name="toc-Introduction-to-LSR-1" href="Introduction-to-LSR.html#Introduction-to-LSR">5.1 Introduction to LSR</a> </li>
<li><a name="toc-Adding-snippets-1" href="Adding-snippets.html#Adding-snippets">5.2 Adding snippets</a> </li>
<li><a name="toc-Approving-snippets-1" href="Approving-snippets.html#Approving-snippets">5.3 Approving snippets</a> </li>
<li><a name="toc-LSR-to-git-1" href="LSR-to-git.html#LSR-to-git">5.4 LSR to git</a> </li>
</ul>
</li>
<li><a name="toc-Issues-1" href="Issues.html#Issues">6. Issues</a>
<ul class="toc">
<li><a name="toc-Introduction-to-issues-1" href="Introduction-to-issues.html#Introduction-to-issues">6.1 Introduction to issues</a> </li>
<li><a name="toc-Issue-classification-1" href="Issue-classification.html#Issue-classification">6.2 Issue classification</a> </li>
<li><a name="toc-Adding-issues-to-the-tracker-1" href="Adding-issues-to-the-tracker.html#Adding-issues-to-the-tracker">6.3 Adding issues to the tracker</a> </li>
</ul>
</li>
<li><a name="toc-Programming-work-1" href="Programming-work.html#Programming-work">7. Programming work</a>
<ul class="toc">
<li><a name="toc-Introduction-to-programming-1" href="Introduction-to-programming.html#Introduction-to-programming">7.1 Introduction to programming</a> </li>
<li><a name="toc-Programming-without-compiling-1" href="Programming-without-compiling.html#Programming-without-compiling">7.2 Programming without compiling</a> </li>
<li><a name="toc-Finding-functions-1" href="Finding-functions.html#Finding-functions">7.3 Finding functions</a> </li>
<li><a name="toc-Code-style-1" href="Code-style.html#Code-style">7.4 Code style</a> </li>
<li><a name="toc-Debugging-LilyPond-1" href="Debugging-LilyPond.html#Debugging-LilyPond">7.5 Debugging LilyPond</a> </li>
</ul>
</li>
<li><a name="toc-Release-work-1" href="Release-work.html#Release-work">8. Release work</a>
<ul class="toc">
<li><a name="toc-Development-phases-1" href="Development-phases.html#Development-phases">8.1 Development phases</a> </li>
<li><a name="toc-Minor-release-checklist-1" href="Minor-release-checklist.html#Minor-release-checklist">8.2 Minor release checklist</a> </li>
<li><a name="toc-Major-release-checklist-1" href="Major-release-checklist.html#Major-release-checklist">8.3 Major release checklist</a> </li>
</ul>
</li>
</ul>
</div>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ffe16b32b9f5eec0add70c0a6bc8cec8
>
files
>
102
