The source content for blog.juliobiason.me
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

120 lines
4.6 KiB

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<!-- Enable responsiveness on mobile devices-->
<!-- viewport-fit=cover is to support iPhone X rounded corners and notch in landscape-->
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1, viewport-fit=cover">
<title>Julio Biason .Me 4.3</title>
<!-- CSS -->
<link rel="stylesheet" href="https://blog.juliobiason.me/print.css" media="print">
<link rel="stylesheet" href="https://blog.juliobiason.me/poole.css">
<link rel="stylesheet" href="https://blog.juliobiason.me/hyde.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=PT+Sans:400,400italic,700|Abril+Fatface">
</head>
<body class=" ">
<div class="sidebar">
<div class="container sidebar-sticky">
<div class="sidebar-about">
<a href="https:&#x2F;&#x2F;blog.juliobiason.me"><h1>Julio Biason .Me 4.3</h1></a>
<p class="lead">Old school dev living in a 2.0 dev world</p>
</div>
<ul class="sidebar-nav">
<li class="sidebar-nav-item"><a href="&#x2F;">English</a></li>
<li class="sidebar-nav-item"><a href="&#x2F;pt">Português</a></li>
<li class="sidebar-nav-item"><a href="&#x2F;tags">Tags (EN)</a></li>
<li class="sidebar-nav-item"><a href="&#x2F;pt&#x2F;tags">Tags (PT)</a></li>
</ul>
</div>
</div>
<div class="content container">
<div class="post">
<h1 class="post-title">Things I Learnt The Hard Way - Good Languages Come With Integrated Documentation</h1>
<span class="post-date">
2019-06-23
<a href="https://blog.juliobiason.me/tags/books/">#books</a>
<a href="https://blog.juliobiason.me/tags/things-i-learnt/">#things i learnt</a>
<a href="https://blog.juliobiason.me/tags/languages/">#languages</a>
<a href="https://blog.juliobiason.me/tags/documentation/">#documentation</a>
</span>
<p>If you're worried about learning some new programming language, you can bet
the one with a better documentation is the one that is <em>born</em> with a document
processor.</p>
<p>Same goes for the frameworks/libraries of that language.</p>
<span id="continue-reading"></span>
<p>The answer for that is the same as <a href="https://blog.juliobiason.me/books/things-i-learnt/languages-docs/languages-tests">languages that come with
tests</a>: because the programming language standard library
comes with a documentation generator or even because documentation is bundled
in the language itself, it reduces the friction needed to start writing the
documentation.</p>
<p>Python is a curious case that it came with a simple documentation generator
(PyDoc) and a bundled documentation format (DocStrings). Nowadays, almost
nobody is using the default documentation generator anymore, but because the
documentation format is still there and is still supported by the language
(documentation appears as a property of every function, class and module),
other tools took the post of default documentation generator, but the
documentation format is still heavy used.</p>
<p>Also, the opposite seems almost always true: If the language doesn't come with
integrated documentation, there is a very good chance that the documentation
or the language or frameworks and libraries will be bad. Or, in the very
least, every library will pick its own format, every framework will pick its
own format and they will never match the language format, and you'll end up
with a mess of a documentation to decipher.</p>
<div>
<div style="float:left">
&lt;&lt; <a href="&#x2F;books&#x2F;things-i-learnt&#x2F;document-and">If A Function Description Includes An And, It&#x27;s Wrong</a>
</div>
&nbsp;
<div style="float:right">
<a href="&#x2F;books&#x2F;things-i-learnt&#x2F;always-vcs">Always Use A Version Control System</a> &gt;&gt;
</div>
</div>
</div>
</div>
</body>
</html>