Ciro Santilli
🔗

Ciro Santilli's documentation superpowers | 🗖 nosplit | ↑ parent "Ciro Santilli's skills" | 559

🔗
Ciro Santilli has the power to document stuff in a way that makes using them awesome, as evidenced by his his Stack Overflow contributions (notably those in the best articles by Ciro Santilli), and other online contributions.
🔗
If your project does something awesome, hiring Ciro means that more people will be able to notice that it is actually awesome, and use it.
🔗
He likes to do this in parallel to contributing new features, quickly switching between his "developer" and "technical documentor" hats.
🔗
This means of course that he will develop new features a bit slower than others, but he feel it is more valuable if end users can actually use your project in the first place.
🔗
His technique is to provide upfront extremely interactive and reproducible getting started setups that immediately show the key value of the project to users.
🔗
He backs those setups with:
  • scripts that automate the setup much as possible to make things enjoyable and reproducible
  • a detailed description of the environment in which he tested: which OS, version of key software, etc.
  • a detailed description of what is expected to happen when you take an action, including known bugs with links to bug reports
  • theory and rationale on the sections after the initial getting started, but always finely interspersed with concrete examples
  • all docs contained in a Git-tracked repo, with the ability to render to a single HTML with one TOC
  • short sentences and paragraphs, interspersed with many headers, lists and code blocks
A prime example of kind of setup is Ciro's Linux Kernel Module Cheat.
🔗
While he create this setup, he inevitably start to notice and fix:
  • bugs
  • annoyances on the public interface of the project
  • the devs were using 50 different local scripts to do similar things, all of them semi-broken and limited. Every new hire was copying one of those local scripts, and hacking it up further.
  • your crappy build / test / version control setup
🔗
Exploiting this skill, however, requires you to trust him.
🔗
When he tells to managers that he's good at documenting, they always say: great, we need better documentation! But then, one of the following may happen:
  • managers forget that they wanted good documentation and just tell him to code new features as fast as possible
  • they don't let him own the getting started page, but rather and expect him to try and fix the existing crappy unfixable existing getting started, without stepping on anyone's pride in the process >:-)
    This makes him tired, and less likely to do a good job.
    Good documentation requires a large number of small iterative reviews, and detailed review of every line is not always feasible.
    Too many cooks.
🔗
Ciro's passion for documentation and tooling has the effect that if you have crappy documentation and tooling and don't want them to be fixed, Ciro will end up trying to fix those tools instead of doing what you tell him to do anyways, which might lead to him quitting because he can't stand the tools, or you firing him because he's not doing the job you think I should be doing. So please, don't bother hiring Ciro if you have crappy documentation and tooling.
🔗
Psychological analysis of why Ciro has this gift: How Ciro Santilli manages to write so much.
🔗
🔗