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

Sean Silva silvas at purdue.edu
Thu Jun 21 21:25:08 PDT 2012


It looks good.

+This Frequently Asked Questions (FAQ) list covers the most common questions
+that will pop up during the process of becoming a skilled technical writer
+for the LLVM project.
I don't like this, now that I think of it. This document isn't really
about technical writing, it's basically a HOWTO about covering
formatting and clerical details of documenting LLVM. I would change
the title to be "How To Write Documentation Q&A".

+The former is gradually being phased-out in favor of the latter so you should
+only really worry about learning the reStructuredText language well.
The last part of this sentence "so you should..." is pointless; it
would make sense if you covered both HTML and reST and the reader "had
to choose" between which one to learn about, but you only cover reST,
so it's pointless. also, put a TODO comment saying to remove this once
everything is Sphinxified.

+A good trick is that most websites that use Sphinx offer a "Show Source"
+link somewhere on the page that has been authored in reStructuredText.
instead of "somewhere on the page", I would say "in the sidebar"

+You can try this out now by clicking on the "View Source" button in the
+menu to the right.
it's "Show Source", and it's not a button. "You can try it out right
now and follow the source as you continue reading this document".

+#. Patches to fix the formatting / structure should go directly to
+   llvm-commits.
+#. Patches to add a FAQ entry to the top level FAQ should at least go to
+   llvm-commits, llvmdev, and possibly a few of the mailing lists for
+   subprojects to get wider feedback.
+#. Patches to other LLVM FAQs should go to llvm-commits and llvmdev.
+#. Patches to other Clang FAQs should go to cfe-dev and cfe-commits.

This list does not cover a lot of cases, like adding a new page.

+Should I indent the outermost lists in a document?
+--------------------------------------------------
put a comment above this with a TODO saying to remove this once all of
the docs have migrated away from this. Also, sink this nearer to the
bottom, since it is relatively trivial compared with other things.

+We try to use the Python style markers (from the Python documentation):
*adornments

+How do I make special markups like ``notice`` and such?
+-------------------------------------------------------
This title is nonsensical given that ``notice`` isn't an admonition at
all. Like I said, "warning" and "tip" are the representative examples,
so they should be in the title.

+Check out the ``.. note::`` admonition in `reStructuredText Directives
+<http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions>`_.
this is completely redundant with the later stuff.

+.. note:: This is an example of a note admonition.
+   To make a note like this, you write:
+
+   .. code-block:: rest
+
+      .. note:: This is a note.
This example is a bit misleading. It would be better if the note
visible to the reader mirrored (as much as possible) the actual note
that it is in. The content of the example note visible to the reader
should be:
+.. note:: This is an example of a note admonition.
+   To make a note like this, you write:
+   ...
(so basically copy the note itself and indent it, putting in an
ellipsis to avoid "infinite recursion" (but make sure it includes at
least the title and a line of the body))

--Sean Silva

On Thu, Jun 21, 2012 at 1:56 PM, Mikael Lyngvig <mikael at lyngvig.org> wrote:
> 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
>>>
>>
>
>




More information about the llvm-commits mailing list