<div dir="ltr">caveat: I'm not an expert in register allocation<div>caveat to the caveat: that means that I'm the audience of this document presumably, so the issues I see are probably representative</div><div><br></div><div>I just got around to reading through your document, and the major thing I see is that there is not a clear organization and is missing the "walkthrough" nature of a true HowTo.</div><div><br></div><div>I would recommend splitting the document into two sections: "concepts" and "walkthrough".</div><div>- The "concepts" covers the background needed to understand the walkthrough.</div><div>- The walkthrough is a numbered list of steps. Each step gives specific instructions for what the reader should do next and advice for how to do it (tips, caveats, etc.). This is a careful balance between just saying "paste this code in" and providing high level details/clarifications. In the case of this document, focus on the things that a reader cannot infer from just reading RegAllocBasic. Having a section "How To Start" at the end under "Tips" which just says "go look at RegAllocBasic" is confusing: the whole point of a HowTo is to describe how to start! You may want "copy RegAllocBasic into RegAllocMyAlloc" as step one of the walkthrough though.</div><div><br></div><div>You already have a lot of the content you need, it's just a matter of organizing it into a clear walkthrough style. Organization is actually *hugely* important for documentation: real documentation reading is highly non-linear (for example, looking back at something earlier in the document, or not understanding something and skimming ahead to see if there is something that helps it make sense). If the reader does not have a clear "map" in their head they will have a very hard time. For example, having explicit numbered steps is actually not necessarily about having somebody read them in that order! It is moreso so that the person reading *knows where they are* in the order.</div><div><br></div><div>-- Sean Silva</div><div><br></div><div><br></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Feb 5, 2016 at 3:50 PM, Natanael Ramos via llvm-commits <span dir="ltr"><<a href="mailto:llvm-commits@lists.llvm.org" target="_blank">llvm-commits@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">Hello<br><br></div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">My name is Natanael Ramos, I'm a  student of bachelor degree on Computer Science Course, here on Brazil.<br><br></div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">Recently I have worked with LLVM for my undergraduate thesis (I don't really know how is called in other countries, here is called <span lang="en"><span>Completion of course work</span></span>), in my work I have implemented an register allocator using LLVM and have tested him with the built-in allocators in LLVM (Probably I'll publish a paper soon, if all goes as expected).<br><br></div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">As another product of my work, I have created a tutorial of how to write an LLVM register allocator, extending the RegAllocBase interface, this tutorial is based on my understanding of the LLVM framework for working with the register allocation pass.<br><br></div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif">The tutorial have been written in reStructuredText following the LLVM instructions and orientations (<a href="http://www.llvm.org/docs/SphinxQuickstartTemplate.html" target="_blank">http://www.llvm.org/docs/SphinxQuickstartTemplate.html</a>). As it's suggested, I'm sending the tutorial to this mailing list<span lang="en"><span> in order to</span> <span>contribute to the community</span> <span>of</span> <span>developers,</span> <span>which</span> <span>use</span> <span>LLLVM.<br><br></span></span></div><div class="gmail_default" style="font-family:arial,helvetica,sans-serif"><span lang="en"><span>Any suggestions, please let me know.<span class="HOEnZb"><font color="#888888"><br></font></span></span></span></div><span class="HOEnZb"><font color="#888888"><div class="gmail_default" style="font-family:arial,helvetica,sans-serif"><span lang="en"><span></span></span></div><br>-- <br><div>Natanael Ramos <br>Membro do corpo discente de Ciência da Computação pelo Instituto Federal de <br>Minas Gerais - Campus Formiga<br><br></div>
</font></span></div>
<br>_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@lists.llvm.org">llvm-commits@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits</a><br>
<br></blockquote></div><br></div>