<!-- 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.4 Tips for writing docs</title> <meta name="description" content="GNU LilyPond Contributor's Guide: 3.4 Tips for writing docs"> <meta name="keywords" content="GNU LilyPond Contributor's Guide: 3.4 Tips for writing docs"> <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-policy.html#Documentation-policy" rel="previous" title="3.3 Documentation policy"> <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="Tips-for-writing-docs"></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-policy.html#Documentation-policy" title="Previous section in reading order" accesskey="p" rel="previous"> < </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="Updating-docs-with-convert_002dly.html#Updating-docs-with-convert_002dly" title="Next section in reading order" accesskey="n" rel="next"> Updating docs with convert-ly > </a>]</td></tr></table> <a name="Tips-for-writing-docs"></a> <h2 class="section">3.4 Tips for writing docs</h2> <p>In the NR, I highly recommend focusing on one subsection at a time. For each subsection, </p> <ul> <li> check the mundane formatting. Are the headings (@predefined, @seealso, etc.) in the right order? </li><li> add any appropriate index entries. </li><li> check the links in the @seealso section – links to music glossary, internal references, and other NR sections are the main concern. Check for potential additions. </li><li> move LSR-worthy material into LSR. Add the snippet, delete the material from the .itely file, and add a @lilypondfile command. </li><li> check the examples and descriptions. Do they still work? <strong>Do not</strong> assume that the existing text is accurate/complete; some of the manual is highly out of date. </li><li> is the material in the @knownissues still accurate? </li><li> can the examples be improved (made more explanatory), or is there any missing info? (feel free to ask specific questions on -user; a couple of people claimed to be interesting in being “consultants” who would help with such questions) </li></ul> <p>In general, I favor short text explanations with good examples – “an example is worth a thousand words”. When I worked on the docs, I spent about half my time just working on those tiny lilypond examples. Making easily-understandable examples is much harder than it looks. </p> <a name="TWEAKS"></a> <h4 class="subsubheading">TWEAKS</h4> <p>In general, any \set or \override commands should go in the “select snippets” section, which means that they should go in LSR and not the .itely file. For some cases, the command obviously belongs in the “main text” (i.e. not inside @predefined or @seealso or whatever) – instrument names are a good example of this. </p> <blockquote><pre class="example"><pre class="example">\set Staff.instrumentName = #"foo" </pre></pre></blockquote> <p>On the other side of this, </p> <blockquote><pre class="example"><pre class="example">\override Score.Hairpin #'after-line-breaking = ##t </pre></pre></blockquote> <p>clearly belongs in LSR. </p> <p>I’m quite willing to discuss specific cases if you think that a tweaks needs to be in the main text. But items that can go into LSR are easier to maintain, so I’d like to move as much as possible into there. </p> <p>It would be “nice” if you spent a lot of time crafting nice tweaks for users... but my recommendation is <strong>not</strong> to do this. There’s a lot of doc work to do without adding examples of tweaks. Tweak examples can easily be added by normal users by adding them to the LSR. </p> <p>One place where a documentation writer can profitably spend time writing or upgrading tweaks is creating tweaks to deal with known issues. It would be ideal if every significant known issue had a workaround to avoid the difficulty. </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-policy.html#Documentation-policy" title="Previous section in reading order" accesskey="p" rel="previous"> < </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="Updating-docs-with-convert_002dly.html#Updating-docs-with-convert_002dly" title="Next section in reading order" accesskey="n" rel="next"> Updating docs with convert-ly > </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><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 class="toc_current"><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>