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

Mikael Lyngvig mikael at lyngvig.org
Wed Jun 20 03:56:23 PDT 2012


Hi Sean,

Oh, I didn't even know you were working on another version.  Feel free to
merge and edit as you want to.  Or to instruct me to merge it into the
existing version.

Thank you very much for the detailed feedback!  I'll fix all of the issues
that you bring up later today when I get some time for it.

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

That's a Danish term that slipped through: udfase (outphase).  I'll fix it.

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

Okay, I'm just trying to give the reader some mental handles to grasp the
new concepts by.   As far as I know, we are using "===" as a chapter
marker, "----" as a section marker, and "^^^" as a subsection marker.  But
I can see the value of sticking to the Sphinx terminology, so I'll fix this
as well.


Regards,
Mikael
-- Disclaimer: I am *not* arrogant in real life, so if you perceive me as
being arrogant, you are to blame ;-)


> --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/ee8c6cba/attachment.html>


More information about the llvm-commits mailing list