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

Mikael Lyngvig mikael at lyngvig.org
Fri Jun 22 12:59:16 PDT 2012


Here's the updated version.  I've changed the name of the document to
"DocumentationFAQ" per your request for a change of title of the document.



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


I've changed the wording to explicitly state that new LLVM FAQs go to
llvm-commits and llvmdev.  Likewise, new Clang FAQs go to cfe-commits and
cfe-dev.

+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.
>

Well, in my experience, you need the note admonition ten times as often as
the warning and tip admonitions.  So I am just trying to help out the
newcomer here.  But, I think I've changed it to reflect your desires.

+.. 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))
>

I ended up doing it somewhat differently: I made a note and then wrote how
to make it outside of it.  It basically looked silly with a note including
a code sample.

>
> --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
> >>>
> >>
> >
> >
>



-- 
-- Disclaimer: I am *not* arrogant in real life, so if you perceive me as
being arrogant, you are to blame ;-)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120622/81142ad2/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: DocumentationFAQ.diff
Type: application/octet-stream
Size: 6917 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120622/81142ad2/attachment.obj>


More information about the llvm-commits mailing list