<html>
<head>
<meta content="text/html; charset=windows-1252"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<p>Along the lines of "write the executive summary first."</p>
<br>
<div class="moz-cite-prefix">On 5/4/16 2:42 PM, Éric Pailleau wrote:<br>
</div>
<blockquote
cite="mid:lgebt067j1lavshrov2titjo.1462386546663@email.android.com"
type="cite">
<p dir="ltr">Hi,<br>
It is certainly unusual, but I almost always start by writing
user documentation, before coding.<br>
There is some interests to do so.<br>
First, documentation exists at end of project because it exists
at beginning. <br>
Second, documentation describe simple things like you would need
as a user, and not complicated things as consequences of bad
coding. Coding is then driven by this goal, and generally
simplify the code itself. <br>
Third, coders know the goal to achieve at start and do not loose
time in, finally, unneeded things.<br>
I really recommend to do this experience. <br>
</p>
<p dir="ltr">"Envoyé depuis mon mobile " Eric</p>
<br>
<br>
---- Grzegorz Junka a écrit ----<br>
<br>
<br>
> - I have said several times that we write code because it is
quicker to<br>
> write it from scratch, than to discover code that does what
we want, or<br>
> modify code that does almost what we want but not quite.<br>
><br>
<br>
That's very true, but it applies all the way through. The more
time has <br>
been invested into some code the more time it would be needed to
write <br>
it from scratch. For example, I would prefer Elixir's convention
of <br>
listing the object on which the operation is being performed as
the <br>
first argument in library function calls over the OTP convention
of <br>
listing it as the last argument. But I am not going to rewrite OTP
<br>
libraries for that small inconvenience.<br>
<br>
Very often understanding an existing application and fixing issues
is <br>
easier and quicker than writing a new one from scratch, especially
if <br>
one only need to understand a specific or small part of it, and
even <br>
more if the existing application supports plugins allowing to skip
large <br>
parts of its code in custom modules.<br>
<br>
This should be a lesson for those who design applications and its
<br>
interfaces, and in my opinion putting effort into designing the <br>
application properly is more important than documenting
everything, <br>
because it's always a trade-off. Very often the documentation
isn't <br>
there not because it's not needed, but because there was not
enough <br>
resources to put it there in the first place.<br>
<br>
If the architecture is good then the documentation can always be
added <br>
later. But if the architecture is not good, then no matter how
much <br>
documentation is written, it will be quickly outdated by the
constant <br>
and often fixes and patches to that architecture to make it
working.<br>
<br>
Grzegorz<br>
_______________________________________________<br>
erlang-questions mailing list<br>
<a moz-do-not-send="true"
href="mailto:erlang-questions@erlang.org">erlang-questions@erlang.org</a><br>
<a moz-do-not-send="true"
href="http://erlang.org/mailman/listinfo/erlang-questions">http://erlang.org/mailman/listinfo/erlang-questions</a><br>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
erlang-questions mailing list
<a class="moz-txt-link-abbreviated" href="mailto:erlang-questions@erlang.org">erlang-questions@erlang.org</a>
<a class="moz-txt-link-freetext" href="http://erlang.org/mailman/listinfo/erlang-questions">http://erlang.org/mailman/listinfo/erlang-questions</a>
</pre>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
In theory, there is no difference between theory and practice.
In practice, there is. .... Yogi Berra</pre>
</body>
</html>