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

Sean Silva silvas at purdue.edu
Wed Jun 20 01:40:45 PDT 2012


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/20120620/403235a1/attachment.html>


More information about the llvm-commits mailing list