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

Mikael Lyngvig mikael at lyngvig.org
Thu Jun 28 05:01:14 PDT 2012 

I forgot to write that I included the updated version as an attachment.
 Please find it in the previous mail from me.

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

> Just ran into this: http://pygments.org/docs/lexers/
> It has all the names of the different syntax highlighting modes.
>
> Please add a link. I think that it is still worthwhile to include the
> most common ones directly though.
>
> Also, sorry for the late reply.
>
> --Sean Silva
>
> On Fri, Jun 22, 2012 at 12:59 PM, Mikael Lyngvig <mikael at lyngvig.org>
> wrote:
> > 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 ;-)
>



-- 
-- Love Thy Frog!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120628/225d3d8c/attachment.html>

More information about the llvm-commits mailing list