Ask HN: How do your team write documentation?

#1

Post by mguijarr » Sun, Nov 19, 2017, 1:36 PM UTC

Hello,

I have got questions regarding documentation writing within a team of software engineers.

Some context:

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:

* the product is a moving target, API is not 100% stable, no one wants to start something and have to redo it later

* everybody in the team prefers to write new features and code than documentation

* the release date seems "far away" (in 18 months)

We follow a kind of scrum methodology, but it is not enough to have documentation stories to get nice documentation ;)

So here are my questions:

* how do you deal with developers writing documentation ?

* are there some techniques that help ?

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

* is it a good idea to hire a "technical writer" to have a specialist writing documentation instead of software engineers ?

* how does it work for open-source projects ? Documentation is sometimes really great, I would like to know the recipe :)

Any help would be appreciated !

Thanks in advance.

Re: Ask HN: How do your team write documentation?

#2

Post by dozzie » Sun, Nov 19, 2017, 2:02 PM UTC

> * 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.

Re: Ask HN: How do your team write documentation?

#3

Post by jklein11 » Sun, Nov 19, 2017, 11:09 PM UTC

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.

Re: Ask HN: How do your team write documentation?

#4

Post by mlazos » Mon, Nov 20, 2017, 6:36 AM UTC

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.

Re: Ask HN: How do your team write documentation?

#5

Post by mguijarr » Mon, Nov 20, 2017, 9:23 AM UTC

jklein11 wrote: post #3

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 i…

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 ?

Re: Ask HN: How do your team write documentation?

#6

Post by mguijarr » Mon, Nov 20, 2017, 9:26 AM UTC

mlazos wrote: post #4

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 correspond…

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.

Re: Ask HN: How do your team write documentation?

#7

Post by jklein11 » Mon, Nov 20, 2017, 2:32 PM UTC

mguijarr wrote: post #5

jklein11 wrote: post #3

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 i…

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 ?

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.

Re: Ask HN: How do your team write documentation?

#8

Post by mlazos » Fri, Nov 24, 2017, 6:36 AM UTC

mguijarr wrote: post #6

mlazos wrote: post #4

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 correspond…

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.

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.