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

[Sean Silva]

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