
Ask HN: How do your team write documentation? - mguijarr
Hello,<p>I have got questions regarding documentation writing within a team of software engineers.<p>Some context:<p>I am a new project leader in the computing department of a medium-sized company. My team is 6 software engineers. We are building a new product, and I cannot get the team to write documentation - we need both an user guide and API documentation too. It is seriously lagging behind, for 3 main reasons I guess:<p>* the product is a moving target, API is not 100% stable, no one wants to start something and have to redo it later<p>* everybody in the team prefers to write new features and code than documentation<p>* the release date seems &quot;far away&quot; (in 18 months)<p>We follow a kind of scrum methodology, but it is not enough to have documentation stories to get nice documentation ;)<p>So here are my questions:<p>* how do you deal with developers writing documentation ?<p>* are there some techniques that help ?<p>* which tools do you use ? I am thinking of gitbook for user guide, and Sphynx for API documentation<p>* is it a good idea to hire a &quot;technical writer&quot; to have a specialist writing documentation instead of software engineers ?<p>* how does it work for open-source projects ? Documentation is sometimes really great, I would like to know the recipe :)<p>Any help would be appreciated !<p>Thanks in advance.
======
dozzie
> * how do you deal with developers writing documentation ?

I do like writing documentation that I will use later myself. I dislike having
to dig through the code of every tool I wrote just to check how it behaves, so
I constantly reach for man pages and, in their absence, for HTML.

I'm in a happy position that all of my tools are later consumed by either
programmers or sysadmins, so I'm certainly my own audience.

> * are there some techniques that help ?

A two-part strategy works for me for API docs: (a) use documentation generator
(a JavaDoc descendant, like Doxygen, EDoc, or Sphinx), and (b) add
docucomments to every function before even writing function's body.

After the (b) part is in place, once the programmer sees that everything else
around has the documentation, he wouldn't want his part to stand out by
looking raw and plain; or at least that's how it works with me.

For documentation about the tool usage, I use anything that fits with the
project's workflow that generates TROFF (man pages). Sometimes it's Perl's
POD, sometimes it's Sphinx.

> * which tools do you use ? I am thinking of gitbook for user guide, and
> Sphynx for API documentation

Sphinx, EDoc, or whatever I have at hand in the language of the project.

Sphinx can also be used for user guide. I don't know much about gitbook, but
given how similar in their essence are all documentation generators (JavaDoc-
like ones), it shouldn't matter that much if you went with gitbook, Sphinx,
raw LaTeX, or a set of Markdown compiled to HTML. Choosing the tool is not the
difficult part.

------
jklein11
This seems like a workflow issue to me.

Writing documentation should come BEFORE writing code. The developer should
know the feature that they are going to implement and how they plan to
implement it before they open the IDE. I've found this keeps me from coding
myself into a corner.

Obviously some things might change, and the documentation will need to be
updated while implementing the feature, but then it is just incremental
changes to already existing documentation.

It shouldn't be a matter of "getting" developers to write documentation.. its
part of the job.

As for a User Guide, I would think this would be the responsibility of the
product owner, or whoever is driving the requirements around what the
application is supposed to do. The developers shouldn't be deciding what the
application does.. just how it does it.

~~~
mguijarr
Thanks for your reply. I have another question though : how would you do if
there were already a lot of undocumented code ? Would you organise a
"documentation retreat" to catch up then doing as you say, documenting before
coding ?

~~~
jklein11
Paying down the technical debt is a tricky one, especially if your application
is large. If you have the cash, it might be worth it to bite the bullet and
hire a consultant/freelance technical writer. Get them to build up the
documentation that you are missing, and then make sure your workflow enforces
that it stays up to date.

------
mlazos
My team at work (Microsoft) uses a custom document renderer based on markdown.
So to enforce good documentation we have two main safeguards. The first is
that we have a static analysis tool that forces everyone to have properly
formatted comments on functions/classes/fields or else the code won’t even
build. The second is more informal but we have a requirement on our team that
every new feature requires a corresponding design doc and that when the
feature is checked in the document gets checked in with it. Subsequent changes
that change the API are also required to change the design doc in order to
pass code review.

~~~
mguijarr
Thanks for your reply. So even at Microsoft developers have to write
documentation themselves ? There are no technical writers to help ? I do not
know how to catch up with the documentation now there are tons of undocumented
code - your ideas are great for ensuring the situation won't reproduce but I
need to catch up too. Thanks.

~~~
mlazos
So for public facing documentation on an API there are technical writers (like
for support docs) but for internal documentation we are expected to keep code
well documented. Yeah it might be good to just start having these safeguards
and as the code base churns it will gradually get fixed.

