CVS: main/DOCS/xml/en encoding-guide.xml,1.36,1.37
CVS change done by Guillaume Poirier CVS Update of /cvsroot/mplayer/main/DOCS/xml/en In directory mail:/var2/tmp/cvs-serv20612/DOCS/xml/en Modified Files: encoding-guide.xml Log Message: New section: choosing the video codec for your encode: what to consider before picking it. Index: encoding-guide.xml =================================================================== RCS file: /cvsroot/mplayer/main/DOCS/xml/en/encoding-guide.xml,v retrieving revision 1.36 retrieving revision 1.37 diff -u -r1.36 -r1.37 --- encoding-guide.xml 6 Dec 2005 00:45:15 -0000 1.36 +++ encoding-guide.xml 27 Dec 2005 09:34:57 -0000 1.37 @@ -1350,6 +1350,111 @@ </para> </sect2> +<sect2 id="menc-feat-dvd-mpeg4-codec"> +<title>Choosing the video codec</title> + +<para> + Choosing the video codec to use depends on several factors, some of + which widely depend on personal taste and technical constraints. +</para> +<itemizedlist> + <listitem><para> + <emphasis role="bold">Compression efficiency</emphasis>: + It's quite easy to understand that newer-generation codecs are made + to yield better picture quality than previous generations. + Therefore, you cannot be wrong + <footnote id='fn-menc-feat-dvd-mpeg4-codec-cpu'> + <para>Be careful, however: decoding DVD-resolution MPEG-4 AVC videos + requires a fast machine (i.e. a Pentium 4 over 1.5Ghz or a Pentium M + over 1Ghz). + </para></footnote> + by choosing MPEG-4 AVC codecs like + <systemitem class="library">x264</systemitem> instead of MPEG-4 ASP codecs + such as <systemitem class="library">libavcodec</systemitem> MPEG-4 or + <systemitem class="library">XviD</systemitem>. + (To get a better grasp of what the fundamental differences between + MPEG-4 ASP and MPEG-4 AVC are, you would be well advised to read the entry + "<ulink url="http://guru.multimedia.cx/?p=10">15 reasons why MPEG4 sucks</ulink>" + from Michael Niedermayer's blog.) + Likewise, you should get better quality using MPEG-4 ASP instead + of MPEG-2 codecs. + </para> + <para> + However, newer codecs which are in heavy development can suffer from + bugs which have not yet been noticed and which can ruin an encode. + This is simply the tradeoff for using bleeding-edge technology. + </para> + <para> + What's more, beginning to use a new codec requires that you spend some + time becoming familiar with its available options, so that you know what + to adjust to achieve a desired picture quality. + </para></listitem> + + <listitem><para> + <emphasis role="bold">Hardware compatibility</emphasis>: + It usually takes a long time for standalone video players to begin to + include support for the latest video codecs. + As a result, most only support MPEG-2 and MPEG-4 ASP + (beware: usually, not all MPEG-4 ASP features are supported). + Please refer to the technical specs of your player (if they are available), + or Google around for more information. + </para></listitem> + + <listitem><para> + <emphasis role="bold">Best quality per encoding time</emphasis>: + Codecs that have been around for some time (such as + <systemitem class="library">libavcodec</systemitem> MPEG-4 and + <systemitem class="library">XviD</systemitem>) are usually heavily + optimized with all kinds of smart algorithms and SIMD assembly code. + That's why they tend to yield the best quality per fps. + However, they may have some very advanced options that, if enabled, + will make the encode really slow for marginal gains. + </para> + <para> + If you are after blazing speed you should stick around the default + settings of the video codec (which doesn't mean you should not experiment + with some of the options which are mentioned in other sections + of this guide). + </para> + <para> + You may also consider choosing a codec which can do multi-threaded + processing. + <systemitem class="library">libavcodec</systemitem> MPEG-4 does + allow that, resulting in small speed gains at the price of lower + picture quality. + <systemitem class="library">XviD</systemitem> has some experimental + patches available to boost encoding speed, by about 40-60% in typical + cases, with low picture degradation. + <systemitem class="library">x264</systemitem> also allows multi-threaded + encoding, which currently speeds-up encoding by 15-30% while lowering + PSNR by about 0.05dB. + </para></listitem> + + <listitem><para> + <emphasis role="bold">Personal taste</emphasis>: + This is where it gets almost irrational: For the same reason that some + hung on to DivX 3 for years when newer codecs were already doing wonders, + some folks will prefer <systemitem class="library">XviD</systemitem> + or <systemitem class="library">libavcodec</systemitem> MPEG-4 over + <systemitem class="library">x264</systemitem>. + </para> + <para> + Make your own judgment, and don't always listen to what some people will + tell you to do or think: The best codec is the one you master the best, + and the one that looks best to your eyes on your display + <footnote id='fn-menc-feat-dvd-mpeg4-codec-playback'> + <para>The same encode may not look the same on someone else's monitor or + when played back by a different decoder, so future-proof your encodes by + playing them back on different setups.</para></footnote>! + </para></listitem> +</itemizedlist> +<para> + Please refer to the section + <link linkend="menc-feat-selecting-codec">selecting codecs and container formats</link> + to get a list of supported codecs. +</para> +</sect2> + <sect2 id="menc-feat-dvd-mpeg4-audio"> <title>Audio</title>
On Tue, Dec 27, 2005 at 10:35:00AM +0100, Guillaume Poirier CVS wrote:
+ Choosing the video codec to use depends on several factors, some of + which widely depend on personal taste and technical constraints.
s/widely depend/depend/ IMO at least
+ <footnote id='fn-menc-feat-dvd-mpeg4-codec-cpu'> + <para>Be careful, however: decoding DVD-resolution MPEG-4 AVC videos
Capitalize after the colon.
+ Therefore, you cannot be wrong + by choosing MPEG-4 AVC codecs like
Therefore, you cannot go wrong choosing or Therefore, you cannot go wrong when choosing
+ What's more, beginning to use a new codec requires that you spend some + time becoming familiar with its available options, so that you know what
IMO there are no unavailable options, so I'd drop 'available' here.
+ (beware: usually, not all MPEG-4 ASP features are supported).
Capitalize both before and after the colon.
+ or Google around for more information.
Google is used as a verb here, so no capitalization.
+ That's why they tend to yield the best quality per fps.
Maybe explain this better, like the Wanderer remarked "quality per encoding time ratio" or similar.
+ settings of the video codec (which doesn't mean you should not experiment
Avoid short forms, some more are used in the text. Diego
Hi, Diego Biurrun wrote:
On Tue, Dec 27, 2005 at 10:35:00AM +0100, Guillaume Poirier CVS wrote:
+ Choosing the video codec to use depends on several factors, some of + which widely depend on personal taste and technical constraints.
s/widely depend/depend/ IMO at least
I'd prefer to leave the word "widely" to emphasize the fact that both personal taste and technical constraints will greatly affect the choice. Other factors aren't too proheminent IMHO. Apart from this one, I'll commit an updated version that features your suggestions. Guillaume
On 12/27/2005 06:58 AM, Diego Biurrun wrote:
On Tue, Dec 27, 2005 at 10:35:00AM +0100, Guillaume Poirier CVS wrote:
+ Choosing the video codec to use depends on several factors, some of + which widely depend on personal taste and technical constraints.
s/widely depend/depend/ IMO at least
If not, then at the very least "widely" is almost certainly not the correct word to use. I'll think about it... the correct term here is somewhat obscure, at least in terms of how readily it springs to mind.
+ Therefore, you cannot be wrong + by choosing MPEG-4 AVC codecs like
Therefore, you cannot go wrong choosing
or
Therefore, you cannot go wrong when choosing
I pointed out this one myself, but apparently not clearly enough.
+ What's more, beginning to use a new codec requires that you spend some + time becoming familiar with its available options, so that you know what
IMO there are no unavailable options, so I'd drop 'available' here.
I rephrased this one extensively - the phrasing was intended to mean "the options it has available to be used". Perhaps "the options it provides" instead of "its available options"?
+ (beware: usually, not all MPEG-4 ASP features are supported).
Capitalize both before and after the colon.
I disagree at least about the former, because this parenthetical comment is in the middle of a sentence. If you had a construction of the form "Most A are X, but (look out) some are Y instead", you wouldn't want to capitalize "Look out", would you?
+ or Google around for more information.
Google is used as a verb here, so no capitalization.
Not necessarily - it can be valid to capitalize it even in that form. I'll yield to your decision on the matter, however, since you do seem to be the one 'in charge'.
+ settings of the video codec (which doesn't mean you should not experiment
Avoid short forms, some more are used in the text.
I noticed a number of these in my commenting run - if I'd realized it was that important, I'd have pointed them out. I thought that the restriction on short forms applied primarily or solely to the man page, and that the rest of the documentation - the topic-specific guides in particular - was allowed to be somewhat more conversational? -- The Wanderer Warning: Simply because I argue an issue does not mean I agree with any side of it. Secrecy is the beginning of tyranny.
On Tue, Dec 27, 2005 at 11:44:43AM -0500, The Wanderer wrote:
On 12/27/2005 06:58 AM, Diego Biurrun wrote:
On Tue, Dec 27, 2005 at 10:35:00AM +0100, Guillaume Poirier CVS wrote:
+ Choosing the video codec to use depends on several factors, some of + which widely depend on personal taste and technical constraints.
s/widely depend/depend/ IMO at least
If not, then at the very least "widely" is almost certainly not the correct word to use. I'll think about it... the correct term here is somewhat obscure, at least in terms of how readily it springs to mind.
How about The choice of video codec depends on several factors, some of which vary widely due to personal taste and technical constraints.
+ What's more, beginning to use a new codec requires that you spend some + time becoming familiar with its available options, so that you know what
IMO there are no unavailable options, so I'd drop 'available' here.
I rephrased this one extensively - the phrasing was intended to mean "the options it has available to be used". Perhaps "the options it provides" instead of "its available options"?
Yes, that's even better.
+ (beware: usually, not all MPEG-4 ASP features are supported).
Capitalize both before and after the colon.
I disagree at least about the former, because this parenthetical comment is in the middle of a sentence. If you had a construction of the form "Most A are X, but (look out) some are Y instead", you wouldn't want to capitalize "Look out", would you?
Not necessarily. I guess this is a matter of personal taste. Guillaume can commit whatever feels better to him.
+ or Google around for more information.
Google is used as a verb here, so no capitalization.
Not necessarily - it can be valid to capitalize it even in that form.
Probably. Again this feels like an issue of personal taste/style to me. I'd go for the lowercase version since I consider it the most common form and it makes sense to me.
+ settings of the video codec (which doesn't mean you should not experiment
Avoid short forms, some more are used in the text.
I noticed a number of these in my commenting run - if I'd realized it was that important, I'd have pointed them out. I thought that the restriction on short forms applied primarily or solely to the man page, and that the rest of the documentation - the topic-specific guides in particular - was allowed to be somewhat more conversational?
I thought about this when I reviewed Guillaume's commit. AFAIU it is considered good style to avoid short forms in written text, but on the other hand it is used as a stylistic device to make texts a little less dry and more conversational. So yes, I assume the "no short forms" rule could or maybe should be revisited. What do you think?
I'll yield to your decision on the matter, however, since you do seem to be the one 'in charge'.
In a way, yes. I used to be the only and nowadays I guess I'm still the main documentation maintainer. But MPlayer is largely a meritocracy, so whoever does the work and/or is competent in a particular area gets to make the decisions. For example Guillaume has taken over the MEncoder parts of the documentation and I'm quite happy with the work he is doing. I won't interfere with what he does there content-wise, since I don't believe in "You do the work, I get to decide and boss you around.". Of course I still review stuff and comment, especially the language part since I have some English skills and for a long time we did not have a native speaker reviewing as well. Sometimes there are situations where you just have to choose between two equivalent alternatives A and B to go with one and be consistent throughout. In that case the ball stops at the maintainer to make a decision. For a long time this has been me, but I'm trying to take input from all sides into account and decide after considering all arguments. Plus, I'm willing to share duties and given that I have far less time now than I used to have I'm happy for everybody that helps me out. What does this long-winded speech amount to? 'In charge' is not a fixed position, you're no less competent in English than I am, on the contrary, and if you keep doing more review work than I do, you might end up taking over the maintainership in that area. I won't stand in the way. BTW, maybe we should fix some of the style guidelines in writing. Diego
On 12/27/2005 01:34 PM, Diego Biurrun wrote:
On Tue, Dec 27, 2005 at 11:44:43AM -0500, The Wanderer wrote:
On 12/27/2005 06:58 AM, Diego Biurrun wrote:
s/widely depend/depend/ IMO at least
If not, then at the very least "widely" is almost certainly not the correct word to use. I'll think about it... the correct term here is somewhat obscure, at least in terms of how readily it springs to mind.
How about
The choice of video codec depends on several factors, some of which vary widely due to personal taste and technical constraints.
I'm still not completely happy about that, since what is actually meant is that "which video codec is best to (use,choose) depends on" et cetera (not a phrase I'd want to commit, too awkward), but it would indeed be an improvement on the latter half of the sentence.
IMO there are no unavailable options, so I'd drop 'available' here.
I rephrased this one extensively - the phrasing was intended to mean "the options it has available to be used". Perhaps "the options it provides" instead of "its available options"?
Yes, that's even better.
I'll commit the change, along with any others which come from this subthread, if no one beats me to them.
Capitalize both before and after the colon.
I disagree at least about the former, because this parenthetical comment is in the middle of a sentence. If you had a construction of the form "Most A are X, but (look out) some are Y instead", you wouldn't want to capitalize "Look out", would you?
Not necessarily. I guess this is a matter of personal taste. Guillaume can commit whatever feels better to him.
Agreed.
Google is used as a verb here, so no capitalization.
Not necessarily - it can be valid to capitalize it even in that form.
Probably. Again this feels like an issue of personal taste/style to me. I'd go for the lowercase version since I consider it the most common form and it makes sense to me.
I don't mind that, really - just pointing out that neither form is necessarily inherently more correct than the other. If we use the verb multiple times in the docs we should standardize on one usage, but which one it is probably makes little difference.
Avoid short forms, some more are used in the text.
I noticed a number of these in my commenting run - if I'd realized it was that important, I'd have pointed them out. I thought that the restriction on short forms applied primarily or solely to the man page, and that the rest of the documentation - the topic-specific guides in particular - was allowed to be somewhat more conversational?
I thought about this when I reviewed Guillaume's commit.
AFAIU it is considered good style to avoid short forms in written text, but on the other hand it is used as a stylistic device to make texts a little less dry and more conversational.
So yes, I assume the "no short forms" rule could or maybe should be revisited. What do you think?
For the man page, which is intended to be dry and technical, I support avoiding short forms in pretty much all cases. For the various other guides, however - especially the ones which are intended to be a way to gently introduce the less experienced users to the ins and outs of advanced encoding and playback - it can sometimes be valuable to be less rigid, and I think it could be worth relaxing the rules there. (I've used the same basic guidelines in refraining from commenting on some aspects of previous commits to a few such guides, which were definitely more conversational than I'd have wanted to let by in the man page.)
I'll yield to your decision on the matter, however, since you do seem to be the one 'in charge'.
In a way, yes. I used to be the only and nowadays I guess I'm still the main documentation maintainer. But MPlayer is largely a meritocracy, so whoever does the work and/or is competent in a particular area gets to make the decisions.
For example Guillaume has taken over the MEncoder parts of the documentation and I'm quite happy with the work he is doing. I won't interfere with what he does there content-wise, since I don't believe in "You do the work, I get to decide and boss you around.".
Oh, agreed, across the board. I'm quite good (or at least I'd like to think so) when it comes to reviewing, for grammar and spelling (and even meaning) and the like, but I'd have a devil of a time trying to write a good explanation of something to begin with even if I understood it in detail; Guillaume has done a very good basic job of doing almost exactly that on a number of occasions, including at least a few where I suspect he does *not* know the subject matter all that intimately. (...somehow I've forgotten how I thought that was relevant...)
Of course I still review stuff and comment, especially the language part since I have some English skills and for a long time we did not have a native speaker reviewing as well.
Sometimes there are situations where you just have to choose between two equivalent alternatives A and B to go with one and be consistent throughout. In that case the ball stops at the maintainer to make a decision.
For a long time this has been me, but I'm trying to take input from all sides into account and decide after considering all arguments. Plus, I'm willing to share duties and given that I have far less time now than I used to have I'm happy for everybody that helps me out.
What does this long-winded speech amount to? 'In charge' is not a fixed position, you're no less competent in English than I am, on the contrary, and if you keep doing more review work than I do, you might end up taking over the maintainership in that area. I won't stand in the way.
I don't know if I'd necessarily want to, or if it would be a good idea given the cycles of activity and laxity in which my reviewing has tended to go (I have fully *fifty* marked documentation commits to review or otherwise revisit in my backlog, dating back to September of '04, and I don't think I've ever gotten to even one of them), but I'm glad to have been made aware of the possibility. We've disagreed, and I've been ruled down, on enough policy points in the past that I'm not quite sure how I'd want to handle them if I did wind up taking over... but that's the sort of bridge that can wait to burn till after being crossed. And I'm aware that "in charge" is not especially fixed or especially formal; that's why I put it in quotes in the first place. 'Sall good.
BTW, maybe we should fix some of the style guidelines in writing.
It might not be a bad idea... is there an existing file to which such could appropriately be added, or would we need to create a new one? (DOCS/tech/documentation-style-guidelines.txt? DOCS/README.maintainers? Something else?) -- The Wanderer Warning: Simply because I argue an issue does not mean I agree with any side of it. Secrecy is the beginning of tyranny.
The Wanderer wrote:
On 12/27/2005 01:34 PM, Diego Biurrun wrote:
On Tue, Dec 27, 2005 at 11:44:43AM -0500, The Wanderer wrote:
On 12/27/2005 06:58 AM, Diego Biurrun wrote:
[..]
IMO there are no unavailable options, so I'd drop 'available' here.
I rephrased this one extensively - the phrasing was intended to mean "the options it has available to be used". Perhaps "the options it provides" instead of "its available options"?
Yes, that's even better.
I'll commit the change, along with any others which come from this subthread, if no one beats me to them.
Yes, please do. I'm no longer feeling competent to decide among the different suggested fixes.
Capitalize both before and after the colon.
I disagree at least about the former, because this parenthetical comment is in the middle of a sentence. If you had a construction of the form "Most A are X, but (look out) some are Y instead", you wouldn't want to capitalize "Look out", would you?
Not necessarily. I guess this is a matter of personal taste. Guillaume can commit whatever feels better to him.
Agreed.
I think it somewhat depends on the length of the sentence, and if the sentence is a full sentence with a subject and a verb, I don't mind having it capitalized. In your example, I would not capitalize it since it's too short, and there's no subject (that I can see).
Avoid short forms, some more are used in the text.
I noticed a number of these in my commenting run - if I'd realized it was that important, I'd have pointed them out. I thought that the restriction on short forms applied primarily or solely to the man page, and that the rest of the documentation - the topic-specific guides in particular - was allowed to be somewhat more conversational?
I thought about this when I reviewed Guillaume's commit.
AFAIU it is considered good style to avoid short forms in written text, but on the other hand it is used as a stylistic device to make texts a little less dry and more conversational.
So yes, I assume the "no short forms" rule could or maybe should be revisited. What do you think?
For the man page, which is intended to be dry and technical, I support avoiding short forms in pretty much all cases. For the various other guides, however - especially the ones which are intended to be a way to gently introduce the less experienced users to the ins and outs of advanced encoding and playback - it can sometimes be valuable to be less rigid, and I think it could be worth relaxing the rules there. (I've used the same basic guidelines in refraining from commenting on some aspects of previous commits to a few such guides, which were definitely more conversational than I'd have wanted to let by in the man page.)
I don't care too much about leaving the rule as it is or not. Just don't expect me to conform with it in my initial proposed patches as I just can't help using the contracted form. I usually remove them each time Diego reminds that rule to me.
I'll yield to your decision on the matter, however, since you do seem to be the one 'in charge'.
In a way, yes. I used to be the only and nowadays I guess I'm still the main documentation maintainer. But MPlayer is largely a meritocracy, so whoever does the work and/or is competent in a particular area gets to make the decisions.
For example Guillaume has taken over the MEncoder parts of the documentation and I'm quite happy with the work he is doing. I won't interfere with what he does there content-wise, since I don't believe in "You do the work, I get to decide and boss you around.".
Oh, agreed, across the board. I'm quite good (or at least I'd like to think so) when it comes to reviewing, for grammar and spelling (and even meaning) and the like, but I'd have a devil of a time trying to write a good explanation of something to begin with even if I understood it in detail; Guillaume has done a very good basic job of doing almost exactly that on a number of occasions, including at least a few where I suspect he does *not* know the subject matter all that intimately.
I've built pretty much all my understanding of the technical details involved in MPlayer and MEncoder myself by googling around, reading articles and following ML threads. That means that I don't pretend that I'm holding the truth. I'm just trying to share the information I got here and there. I try as much as possible to double check the informations by checking different sources, when available. What I'm trying to get at is that I consider myself a mere Joe Six Pack user who's just willing to help the community out. So, you're quite all right, I don't know intimately most of the subjects I talk about in the docs ;-P. [..] Guillaume
On 12/28/2005 04:27 AM, Guillaume Poirier wrote:
The Wanderer wrote:
On 12/27/2005 01:34 PM, Diego Biurrun wrote:
Yes, that's even better.
I'll commit the change, along with any others which come from this subthread, if no one beats me to them.
Yes, please do. I'm no longer feeling competent to decide among the different suggested fixes.
Acknowledged. I don't have a lot of time just now, but I should be able to get to these this evening.
Not necessarily. I guess this is a matter of personal taste. Guillaume can commit whatever feels better to him.
Agreed.
I think it somewhat depends on the length of the sentence, and if the sentence is a full sentence with a subject and a verb, I don't mind having it capitalized. In your example, I would not capitalize it since it's too short, and there's no subject (that I can see).
I don't particularly agree with that, but I'll go with the will of the majority (if there happens to be any such) in this instance.
I thought about this when I reviewed Guillaume's commit.
AFAIU it is considered good style to avoid short forms in written text, but on the other hand it is used as a stylistic device to make texts a little less dry and more conversational.
So yes, I assume the "no short forms" rule could or maybe should be revisited. What do you think?
For the man page, which is intended to be dry and technical, I support avoiding short forms in pretty much all cases. For the various other guides, however - especially the ones which are intended to be a way to gently introduce the less experienced users to the ins and outs of advanced encoding and playback - it can sometimes be valuable to be less rigid, and I think it could be worth relaxing the rules there. (I've used the same basic guidelines in refraining from commenting on some aspects of previous commits to a few such guides, which were definitely more conversational than I'd have wanted to let by in the man page.)
I don't care too much about leaving the rule as it is or not. Just don't expect me to conform with it in my initial proposed patches as I just can't help using the contracted form. I usually remove them each time Diego reminds that rule to me.
Oh, not a problem, there are reasons doc patches get submitted for review and catching things like this is one of them. ^_^
In a way, yes. I used to be the only and nowadays I guess I'm still the main documentation maintainer. But MPlayer is largely a meritocracy, so whoever does the work and/or is competent in a particular area gets to make the decisions.
For example Guillaume has taken over the MEncoder parts of the documentation and I'm quite happy with the work he is doing. I won't interfere with what he does there content-wise, since I don't believe in "You do the work, I get to decide and boss you around.".
Oh, agreed, across the board. I'm quite good (or at least I'd like to think so) when it comes to reviewing, for grammar and spelling (and even meaning) and the like, but I'd have a devil of a time trying to write a good explanation of something to begin with even if I understood it in detail; Guillaume has done a very good basic job of doing almost exactly that on a number of occasions, including at least a few where I suspect he does *not* know the subject matter all that intimately.
I've built pretty much all my understanding of the technical details involved in MPlayer and MEncoder myself by googling around, reading articles and following ML threads. That means that I don't pretend that I'm holding the truth. I'm just trying to share the information I got here and there. I try as much as possible to double check the informations by checking different sources, when available.
What I'm trying to get at is that I consider myself a mere Joe Six Pack user who's just willing to help the community out. So, you're quite all right, I don't know intimately most of the subjects I talk about in the docs ;-P.
Which makes it all the more impressive that you've managed to write the documentation sections you have on some of those subjects. As I said, I would have a devil of a time trying to write a good explanation even of something I understood in detail; you've managed to produce mostly creditable or better explanations of things you *don't*, and that's quite an achievement from my perspective. -- The Wanderer Warning: Simply because I argue an issue does not mean I agree with any side of it. Secrecy is the beginning of tyranny.
On Wed, Dec 28, 2005 at 01:58:28PM -0500, The Wanderer wrote:
Which makes it all the more impressive that you've managed to write the documentation sections you have on some of those subjects. As I said, I would have a devil of a time trying to write a good explanation even of something I understood in detail;
Maybe you should just give it a go. (Good) writing skill is not something that you are born with, pretty much like everything else it is 10% talent and 90% sweat. Writing is often called an art, but this is plain wrong, it's a craft. I've given a presentation about writing (good) documentation at LinuxTag, I'll try to summarize some of the central points about the writing part below. The problem many (all?) people face when they have to sit down and write something is the blank sheet of paper (or computer screen, but let's keep the paper analogy for now, it applies to electronic writing as well). It happens to me all the time. For me getting started is the hardest part and after I have somehow produced a rough skeleton of the content I manage to expand and refine it in a fraction of the time it took me to get to that first milestone. So how do I manage to make that initial phase less painful and more productive? Remember the old piece of coding wisdom "Avoid premature optimization."? It applies to writing as well, let me explain how. Say you have written down that magic first sentence. You don't like it, so you rewrite it; four times. You arrive at 20 pages of text and start the review phase. You go back to your perfect first sentence only to discover that given the 20 pages of text that appeared after it, it's no longer the perfect fit it used to be. You throw it away and rewrite it, only twice this time. Your work is finally finished and you start the last review cycle. You have a new idea for a better introduction and write a new first sentence from scratch, for the nth time. So how do I avoid this situation? Usually writing works in iterations. First you create a rough draft, then you refine it n times. Accept that the first draft is just that - a draft - and that draft quality is more than sufficient for it. If you try to produce a high quality draft, you will WASTE TIME in big quantities. Doesn't "high quality draft" sound like a contradiction in itself? It does, because it is, so don't try to achieve the impossible. Still creating that first draft is not trivial and avoiding the above-mentioned pitfalls can be difficult. Here are two techniques that I find effective: 1) bulletted lists Bulletted lists are great because they free you completely of grammar and style and quality concerns. You can start jotting down ideas in no particular order until you run out of ideas or until you have listed everything that you want your written work to contain. The temptation to "optimize" bulletted lists is near-zero. Once you have a list of things you can start reordering the bullet points, adding a bit here and there, giving the list more structure to make it resemble a rough outline of the text you want to produce. Then you can add more details, start writing chapters, etc. Just remember that even now you WILL throw away the first version, so don't waste too much time on it. 2) automatic writing This is a technique from creative writing that is used to combat writer's block and works quite well to produce first drafts and ideas. Here's how it works: Grab pen and paper and set an alarm clock to a fixed amount of time (fifteen minutes as a rough guideline). Then start writing and during the set amount of time you may never, under no circumstances, stop writing. Style, orthography, even grammar, toss it all aside and write. If you hit a block and hesitate, you can use an escape rule. Repeat the last word/sentence, write something that rhymes, starts with the same letter, whatever. Anything that keeps the pen pressed to the paper is fine. When the alarm goes off, drop the pen (or continue if you are in a flow) and review what you have written. Results are often surprising and even if not, normally you have a draft that can be refined into something useful. OK, I'm cutting down on it here, it's been pretty long-winded already, but I thought I might share some of my experience with you. I often find writing quite hard and these techniques help me a lot. So, don't worry Wanderer, I'm sure you can pick up writing skills with a bit of patience. Guillaume probably did it without worrying too much about the outcome beforehand, which is pretty much the spirit of the above-mentioned techniques. Diego
Diego Biurrun wrote:
AFAIU it is considered good style to avoid short forms in written text, but on the other hand it is used as a stylistic device to make texts a little less dry and more conversational.
So yes, I assume the "no short forms" rule could or maybe should be revisited. What do you think?
I vote for removing that rule. Excessive use of contractions detracts from the formality of text, but using them sparingly and in appropriate places makes the wording flow more naturally. Contractions can also be used to redirect emphasis. For example, suppose I were trying to explain the proper usage of qns: 1. qns is not very fast, but it makes sharp edges look much nicer at low bitrates 2. qns isn't very fast, but it makes sharp edges look much nicer at low bitrates The first form places extra emphasis on "is not very fast", which is not the point I'm trying to make. The previous sentence is an example as well -- I intentionally used "is not" and "I'm" to increase and decrease emphasis in their respective places. In the end, it's a matter of style. I don't know if there are any formal, generally-accepted documentation rules that prohibit contractions, but I prefer to use them now and then in my general writing. -Corey
On Tue, Dec 27, 2005 at 04:47:16PM -0800, Corey Hickey wrote:
Diego Biurrun wrote:
AFAIU it is considered good style to avoid short forms in written text, but on the other hand it is used as a stylistic device to make texts a little less dry and more conversational.
So yes, I assume the "no short forms" rule could or maybe should be revisited. What do you think?
[ explanation ]
In the end, it's a matter of style. I don't know if there are any formal, generally-accepted documentation rules that prohibit contractions, but I prefer to use them now and then in my general writing.
OK, I propose going with the Wanderer's suggestion then: Avoid short forms in the more formal man page, allow them in the rest of the documentation where a more informal writing style is adequate. Diego
Diego Biurrun wrote:
AFAIU it is considered good style to avoid short forms in written text, but on the other hand it is used as a stylistic device to make texts a little less dry and more conversational.
So yes, I assume the "no short forms" rule could or maybe should be revisited. What do you think?
[ explanation ]
In the end, it's a matter of style. I don't know if there are any formal, generally-accepted documentation rules that prohibit contractions, but I prefer to use them now and then in my general writing.
OK, I propose going with the Wanderer's suggestion then: Avoid short forms in the more formal man page, allow them in the rest of the documentation where a more informal writing style is adequate.
That's fine with me. -Corey
participants (5)
-
Corey Hickey -
Diego Biurrun -
Guillaume Poirier -
syncmail＠mplayerhq.hu -
The Wanderer