<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Sat, Aug 27, 2016 at 12:51 AM, Christopher J. Morrone <span dir="ltr"><<a href="mailto:morrone2@llnl.gov" target="_blank">morrone2@llnl.gov</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 08/26/2016 12:48 PM, Oleg Drokin wrote:<br>
<br>
> (it's best to be written by third parties anyway since once you work too much<br>
> on some code, you take too many things for granted/think they are obvious,<br>
> and then the end result has gaps that make it hard on the outsiders).<br>
<br>
</span>That is an common excuse that I hear around these parts, but I simply do<br>
not accept that axiom.<br>
<br>
Yes, there is a kernel of truth that developers can write documentation<br>
that is less than helpful at times for a myriad of reasons.  But none of<br>
those reasons are an adequate excuse for the rather extreme abdication<br>
of documentation responsibility that Lustre tends to adopt.<br>
<br>
There are numerous ways to address the issue of the developers taking<br>
too many things for granted, or failing to document because they seem<br>
too obvious.<br>
<br>
First of all, I would argue that this is most likely to happen when the<br>
developers do not practice documenting on a regular basis as an<br>
integrated part of the development process.  If it is a common, required<br>
process, many developers will get better at it over time.<br>
<br>
Then there are reviews.  Good peer review of documentation will catch<br>
many bad assumptions in the same way that good peer review catches<br>
assumptions and mistakes in code.<br>
<br>
And then after the review process, we should understand that design<br>
documentation is a living document that is always growing and improving,<br>
much like the code itself.  When outsiders or new developers point out<br>
unclear parts that remain after reviews, those sections can _still_ be<br>
improved!<br>
<br>
The real reason that documentation doesn't happen is not because<br>
developers are incapable of doing it well.  I would argue that a<br>
software developer incapable of documenting their designs, apis, on disk<br>
formats, etc., is a person lacking a significant software development<br>
skill for software projects of any significant size and/or complexity.<br>
<br>
I think instead that most of the core Lustre developers don't _want_ to<br>
do it and not enough of the managers of those developers are willing to<br>
_make_ them do it for whatever reasons.<br>
<br>
Sure, we _can_ all sit around hoping that some day an external entity<br>
can come along again to cough up a bunch of money to make a one-time<br>
burst at design documents.  That is largely what we're doing, and it<br>
isn't working very well.  That method is pretty clearly not sustainable,<br>
and does not result in maintained documentation.<br>
<br>
Will this ever change in Lustre?  Probably not.  We are very set in our<br>
ways.  Change is hard.<br></blockquote><div>I hope your prediction is wrong because good quality docs is one of the biggest missing things (other then seamless mainline kernel integration), though I may be wrong it seems to me that even from a commercial point of view it makes more sense for Intel that there should be good docs..... <br></div><div>Am now finally going to read this doc.<br></div><div>Eli<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
But I will happily eat crow if it does.<br>
<br>
Chris<br>
<br>
______________________________<wbr>_________________<br>
lustre-discuss mailing list<br>
<a href="mailto:lustre-discuss@lists.lustre.org">lustre-discuss@lists.lustre.<wbr>org</a><br>
<a href="http://lists.lustre.org/listinfo.cgi/lustre-discuss-lustre.org" rel="noreferrer" target="_blank">http://lists.lustre.org/<wbr>listinfo.cgi/lustre-discuss-<wbr>lustre.org</a><br>
</blockquote></div><br></div></div>