Ask HN: How do your team write documentation?

6 点作者 mguijarr超过 7 年前

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.

3 条评论

dozzie超过 7 年前

> * 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 documentationSphinx, 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超过 7 年前

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.

评论 #15738756 未加载

mlazos超过 7 年前

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.

评论 #15738773 未加载