[llvm-commits] [PATCH] [NEW] Technical Writing FAQ (1ST TRY)

Thu Jun 21 13:56:42 PDT 2012

Hi Sean,

Here's the updated version with your suggestions.

Regards,
Mikael
-- Disclaimer: I am *not* arrogant in real life, so if you perceive me as
being arrogant, you are to blame ;-)

2012/6/20 Sean Silva <silvas at purdue.edu>

> 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.
>
> 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.
>
> 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 :-)
>
> 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.
>
> Comments about the document itself:
>
> +#. Raw HTML with a Cascading Style Sheet (CSS) file.
> I think you can just say "Raw HTML" here. CSS is presentational and not
> part of "writing the docs"
>
> +The former is gradually being outphased in favor of the latter so you
> should
> 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.
>
> +You basically edit, using an ordinary text editor (not a word processor),
> the
> I don't think this comment about a word processor is necessary. Remember
> your audience.
>
> +Some hints:
> + [...]
> These are not "hints"; they are phrased as rules.
>
> +#. reStructured Text files end in the extension ``.rst``.
> reStructuredText is one word.
>
> +#. Keep each line, except section headers, at maximum 79 characters.
> LLVM convention is 80
>
> + [...] But the entire Sphinx website is
> +full of interesting information relating to Sphinx.
> 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.
>
> +A good trick is that most websites that use Sphinx offer a ``View code``
> 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.
>
> +What are ``llvm-commits`` and ``llvmdev``?
> 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
> "Changes should be submitted to the `mailing lists <mailing_lists>`_ as
> follows:"
>
> +What markers should I use for chapter and section headers?
> The reST specification refers to these "markers" as "adornment styles" <
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections
> >
>
> +   Major Division 1 (Chapter)
> I don't think ==== means "chapter" at all. The Sphinx documentation <
> http://sphinx.pocoo.org/rest.html#sections> mentions the breakdown for
> adornments used by the Python docs (which we are trying to follow), and it
> says ==== means "section"
>
> +Avoid using the ``::`` operator.  Instead, you have to use the
> ``code-block``
> +command.
> The Sphinx docs call :: a "marker", not an "operator" <
> http://sphinx.pocoo.org/rest.html#source-code>. 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"
>
> +whenever there's code embedded in the text), you insert a ``code-block``
> +statement like this:
> Thank you for giving an example here! ``code-block`` is a "directive", not
> a "statement" though.
>
> +The list is huge.  Check it out at the `Pygments website
> +<http://pygments.org/languages/>`_.
> 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.
>
> + [...] Unfortunately, there's no explicit list
> +of the actual names to use with ``code-blocks``
> OMG, yes! This is so annoying. Also, the "s" in ``code-blocks`` should be
> outside the `` `` quotes.
>
> +[...]Here's a list of the most
> +commonly used languages in the LLVM world:
> 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"
>
> +#. LLVM: ``llvm``
> I would say "LLVM IR" just to be extra clear.
>
> +#. reStructured Text: ``rest``
> reST doesn't have a space before Text
>
> +Why do my numbered lists not work?
> +----------------------------------
> Thank you for bringing this up, as it has the potential to be *very*
> confusing.
>
> +How do I make special sections like ``notice`` and such?
> +--------------------------------------------------------
> +Check out ``.. note::`` and friends in `reStructured Text Directives
> +<http://docutils.sourceforge.net/docs/ref/rst/directives.html#note>`_.
> 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 <
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions>
> 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
>
> .. note::
>    To make a note like this, do ...
>    [...]
>    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 <
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
> >`_.
>
> Sorry for the 80-column violation, my mail client is not my usual editing
> environment.
>
> --Sean Silva
>
> On Tue, Jun 19, 2012 at 1:28 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>
>> Hi,
>>
>> 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.
>>
>> 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.
>>
>>
>> Cheers,
>> Mikael
>> -- Disclaimer: I am *not* arrogant in real life, so if you perceive me
>> as being arrogant, you are to blame ;-)
>>
>> _______________________________________________
>> llvm-commits mailing list
>> llvm-commits at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120621/bc050201/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: TechnicalWritingFAQ.diff
Type: application/octet-stream
Size: 6887 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120621/bc050201/attachment.obj>