I specifically starred the previous one and have been wanting to get back to it. It is a pretty long document, so there is naturally a lot to say about it. I guess I'll abandon it now, as we can use this lightweight version as a starting point.<div>
<br></div><div>I was generally very impressed with the content and liked it. The Question&Answer style seemed to fit well with the nature of the material.</div><div><br></div><div>This lightweight Technical Writing FAQ seems to be excellent in that it distills the things you have learned from myself and other reviewers for your own documentation submissions; I think it will be highly beneficial for . If we all produced such distillations when we learned about a particular part of LLVM, then all of our documentation problems would be solved :-)</div>
<div><br></div><div>I choked on one particular thing that I couldn't quite put my finger on, but that I think I can articulate now. In my mind, I envision people contributing to the LLVM docs as having some experience with LLVM already. We can assume a number of things, such as, for example, that they know C++, so we can display a C++ fragment without any fanfare. I think that it is safe to assume that anybody that is going to be writing LLVM docs is going to have the source code checked out and be familiar with their version-control system. So a question like "How do I get access to the LLVM documentation source files?" need not exist. Perhaps "where are the LLVM docs files located?" and the answer would be "in the docs/ directory of the LLVM source tree". Leveraging assumptions like this can improve the documentation by making it briefer and more dense with information relevant to the audience. I'm sure the people on this list would be happy to provide feedback on any questions regarding whether something is a safe assumption.</div>
<div><br></div><div>Comments about the document itself:</div><div><br></div><div>+#. Raw HTML with a Cascading Style Sheet (CSS) file.</div><div>I think you can just say "Raw HTML" here. CSS is presentational and not part of "writing the docs"</div>
<div><br></div><div>+The former is gradually being outphased in favor of the latter so you should</div><div>I think you mean "phased-out". I have never seen "outphased" used before. Google hits for "outphased" are unrelated (or vaguely-related) to this usage.</div>
<div><br></div><div>+You basically edit, using an ordinary text editor (not a word processor), the</div><div>I don't think this comment about a word processor is necessary. Remember your audience.</div><div><br></div>
<div>+Some hints:</div><div>+ [...]</div><div>These are not "hints"; they are phrased as rules.</div><div><br></div><div>+#. reStructured Text files end in the extension ``.rst``.</div><div>reStructuredText is one word.</div>
<div><br></div><div>+#. Keep each line, except section headers, at maximum 79 characters.</div><div>LLVM convention is 80</div><div><br></div><div><div>+ [...] But the entire Sphinx website is</div><div>+full of interesting information relating to Sphinx.</div>
<div>This sentence doesn't say anything. It is obvious that the Sphinx website will be about Sphinx, so all this is really saying is that the information there is "interesting". I think it would be better to say something useful, like "The Sphinx website contains thorough documentation about Sphinx usage and the reStructuredText format". Also "Sphinx website" should be a link to their homepage.</div>
<div><br></div><div>+A good trick is that most websites that use Sphinx offer a ``View code``</div><div>The canonical name for this link is "Show Source". I have never seen "View code". Also, why is it monospaced? Quotes or italics is much more fitting. I would recommend leveraging this as part of this document by inviting the reader to click this link and have the source up side-by-side as they continue reading.</div>
<div><br></div><div>+What are ``llvm-commits`` and ``llvmdev``?</div><div>This is another case where I think we can assume that the audience will be aware of what these are. It might still be beneficial to add an introductory sentence leading the section titled "How do I submit my changes to the LLVM documentation?" with the content</div>
<div>"Changes should be submitted to the `mailing lists <mailing_lists>`_ as follows:"</div><div><br></div><div>+What markers should I use for chapter and section headers?</div><div>The reST specification refers to these "markers" as "adornment styles" <<a href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections">http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections</a>></div>
<div><br></div><div>+ Major Division 1 (Chapter)</div><div>I don't think ==== means "chapter" at all. The Sphinx documentation <<a href="http://sphinx.pocoo.org/rest.html#sections">http://sphinx.pocoo.org/rest.html#sections</a>> mentions the breakdown for adornments used by the Python docs (which we are trying to follow), and it says ==== means "section"</div>
<div><br></div><div><div>+Avoid using the ``::`` operator. Instead, you have to use the ``code-block``</div><div>+command.</div></div><div>The Sphinx docs call :: a "marker", not an "operator" <<a href="http://sphinx.pocoo.org/rest.html#source-code">http://sphinx.pocoo.org/rest.html#source-code</a>>. And ``code-block`` is a "directive", not a "command". More importantly, the tone of these two sentences is completely contradictory. One says "avoid", while the other says "you have to". Better to say "Prefer to use the ``code-block`` directive over a bare ``::`` marker to introduce code snippets"</div>
<div><br></div><div><div>+whenever there's code embedded in the text), you insert a ``code-block``</div><div>+statement like this:</div></div><div>Thank you for giving an example here! ``code-block`` is a "directive", not a "statement" though.</div>
<div><br></div><div><div>+The list is huge. Check it out at the `Pygments website</div><div>+<<a href="http://pygments.org/languages/">http://pygments.org/languages/</a>>`_.</div></div><div>It is confusing to mention Pygments out of the blue. You should briefly note that Pygments is the package that Sphinx uses for syntax highlighting before linking to the Pygments language list.</div>
<div><br></div><div><div>+ [...] Unfortunately, there's no explicit list</div><div>+of the actual names to use with ``code-blocks``</div></div><div>OMG, yes! This is so annoying. Also, the "s" in ``code-blocks`` should be outside the `` `` quotes.</div>
<div><br></div><div><div>+[...]Here's a list of the most</div><div>+commonly used languages in the LLVM world:</div></div><div>It's not a list of languages, it's a list of names for those languages. "Here's a list of names for the most commonly used languages in the LLVM world"</div>
<div><br></div><div>+#. LLVM: ``llvm``</div><div>I would say "LLVM IR" just to be extra clear.</div><div><br></div><div>+#. reStructured Text: ``rest``</div><div>reST doesn't have a space before Text</div><div>
<br></div><div><div>+Why do my numbered lists not work?</div><div>+----------------------------------</div></div><div>Thank you for bringing this up, as it has the potential to be *very* confusing.</div><div><br></div><div>
<div>+How do I make special sections like ``notice`` and such?</div><div>+--------------------------------------------------------</div><div>+Check out ``.. note::`` and friends in `reStructured Text Directives</div><div>
+<<a href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#note">http://docutils.sourceforge.net/docs/ref/rst/directives.html#note</a>>`_.</div></div><div>The general name for these constructs is "admonitions". I think it would be worth mentioning that, since that is the key term for Googling to learn more about it. Also, the link should probably be <<a href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions">http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions</a>> even though it appears to link to the same place. Also, "notice" isn't one of the admonitions, and admonitions aren't "sections". The representative examples of admonitions are "tip", "warning", and "note". Also, to be even more clear, I would put this actual question inside an admonition itself, as in</div>
<div><br></div><div>.. note::</div><div> To make a note like this, do ...</div><div> [...]</div><div> There are also similar directives for "warning" and "tip", among others. The general name for these constructs is "admonitions", and a full reference can be found on the `reStructuredText specification <<a href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions">http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions</a>>`_.</div>
<div><br></div><div>Sorry for the 80-column violation, my mail client is not my usual editing environment.</div><div><br></div><div>--Sean Silva</div><div><br></div><div><div class="gmail_quote">On Tue, Jun 19, 2012 at 1:28 PM, Mikael Lyngvig <span dir="ltr"><<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi,<div><br></div><div>I've written a tiny, light-weight Technical Writing FAQ for those of us who venture into the land of converting existing HTML to Sphinx or even writing new documentation. I posted it to LLVMdev, but got not a single reply. </div>
<div><br></div><div>I have intentionally not linked it into the existing documentation because I have no clue where to put it. I figure that the person who checks the document in, if it is accepted that is, can link it in somewhere.</div>
<div><br></div><div><br></div><div>Cheers,</div><div>Mikael<br clear="all"><div>-- Disclaimer: I am <b>not</b> arrogant in real life, so if you perceive me as being arrogant, you are to blame ;-)</div>
</div>
<br>_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@cs.uiuc.edu">llvm-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits</a><br>
<br></blockquote></div><br></div></div>