
Ask HN: How does your team write documentation? What tools do you use? - brwr
We&#x27;re trying to get better at writing docs, so I thought I&#x27;d turn to you guys for help.<p>How does your team write documentation? What part of the documentation (e.g. architecture, processes, tooling) do you give the most attention to? What tools have you found helpful in improving the documentation your team writes?
======
skewart
I really like these "how do other people do X?" questions on HN. Thanks for
asking it!

I work at a small startup with a roughly 10-person eng team.

When we write docs we focus mainly on architecture and processes. The
architecture docs often emerge from a "tech spec" that was written for the
development of a feature that required a new service, or substantial changes
to a new one. We keep everything in Github, in a README or other markdown
files.

We also write API docs for HTTP endpoints. These are written with client
developers and their concerns in mind. When doing this for a Rails app we use
rspec_API_documentation, which is nice, but it can be annoying to have testing
and documentation so tightly couples. We've talked about changing how we do
this, but we always have more pressing things to do.

We never write docs for classes or modules within an app/service.

~~~
brwr
My pleasure! Questions like these are a great way to get a large set of
informed opinions quickly.

Regarding your comment on considering changing your API docs: What have you
and your team talked about moving to?

Also, why no class or module docs? I find a docstring at the top of the class
that talks about it's implementation, usage, etc very helpful.

------
azdle
All of our docs a written in Markdown in a git repo [1]. That then gets built
with a custom static site generator that I wrote [2]. Finally the output gets
pushed back to gh for hosting on gh-pages [3].

I'm actually pretty proud of the search that I put together for this setup
too, it's all done in the browser and the indexes are built at compile time
which is then downloaded in full for a search, which sounds silly, but it
works surprisingly well [4].

[1] [https://github.com/exosite/docs/](https://github.com/exosite/docs/)

[2]
[https://github.com/exosite/docs/blob/master/gulpfile.js](https://github.com/exosite/docs/blob/master/gulpfile.js)

[3] [http://docs.exosite.com](http://docs.exosite.com)

[4]
[http://docs.exosite.com/search.html?q=subscribe](http://docs.exosite.com/search.html?q=subscribe)

~~~
brwr
That's so cool! It blows my mind that the search is done in-browser.

~~~
azdle
Yeah, when I was writing that I was just kinda hacking something together to
see if it was possible and it ended up working so well that I pushed it out.
Probably could still use a bit of polish yet.

Would anyone be interested in a write-up of how I put it together? It might
finally be something to post to one of the umpteen blogs I've setup and never
used.

~~~
brwr
I'd definitely be interested. :)

------
tvvocold
We use flatdoc and Swagger UI for building docs, like:
[https://open.coding.net](https://open.coding.net)

flatdoc is a small JavaScript file that fetches Markdown files and renders
them as full pages:
[https://github.com/rstacruz/flatdoc](https://github.com/rstacruz/flatdoc)

Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets
that dynamically generate beautiful documentation from a Swagger-compliant
API. [http://swagger.io](http://swagger.io)

------
imrehg
Word docs converted into PDF for manuals. Some other are hand-crafted
Photoshop tables/text/graphics to create PDF. Sad, sad stuff, IMHO.

Trying to get people onto Sphinx [0], and use it for some non-sanctioned
documentation with good success, but unlikely to make it official.

I really think version control is important: what changed, who changed it,
provisional changes through branches, and removing the bottleneck of "I
updated the docs, please everyone check before release and send me your
comments". It should be patches, and only patches.

[0]: [http://sphinx-doc.org/](http://sphinx-doc.org/)

~~~
brwr
Over time I've noticed that a lot of software developers aren't good
documentation writers. I'm not saying this is good or bad, but it is a
statement I believe to be true.

With that said, what advantages are there to removing the bottleneck of "I
updated the docs, please everyone check before release and send me your
comments"? To me, personally, letting anyone update the docs without review
sounds like a recipe for trouble.

~~~
imrehg
Yeah, very few people are good documentation writers. After writing up a lot
of maker projects I found that I like to do docs, and that makes me also more
demanding regarding the quality of the docs I need to feedback on. It would be
great if people would put more time in it to become better, and another reason
why I like sort-of self-documenting tools (e.g. Rust, where documentation is
taken seriously from the beginning of the project).

I didn't mean everyone can update the docs, rather send feedback by patch/pull
request of actual changes instead of writing in email with words that "Rewrite
header 1 to be X, add label Y to figure 2, and add date into footer".
Currently bloody Word Docs and PDFs are sent around twice a day for "please
reply with your comments", and things get lost between emails, changes that
were applied before disappear because someone edited the wrong version of the
Doc, or exported into PDF in the wrong way... All in all, changes shouldn't
happen in email text, IMHO.

Whether anyone can edit the docs - I'd actually like to see that (even if I
haven't said that originally). Currently even the people who are charged with
maintaining the docs update it only when pushed, I think in most places you'd
be lucky if anyone touches it. On the other hand, an empowered team where
anyone can access improve on things is a very different feeling, that's what
creates successful stuff, IMHO. And with version control failure is cheap and
easy to fix, so there's very little downside. Think of large public projects
like OpenStreetMap or the Embedded Linux Wiki at
[http://elinux.org](http://elinux.org) It works out pretty well for them with
no big trouble, and they literally let everyone change things (not just
project members).

------
chris_engel
Because I was not happy with the existing stuff, I've built an opensource
project for creating technical online documentations some time ago, named
"docEngine". My goals were:

\- Easy editing (namely markdown files in folders) \- Runs on "cheap"
hosting/everywhere (built with PHP) \- Supports multiple languages (so you can
create docs in english, german, etc.) \- Can have editable try-on-your-own
demos embedded into the documentation \- SEO friendly (clean URLs and
navigation structure) \- Themeable (themes are separated and run with the Twig
templating engine) \- Works on mobiles out of the box \- Supports
Plugins/Modules for custom content/behaviour \- Formats reference pages for
objects/classes/APIs in a nice way \- Supports easy embedding of disqus for
user feedback \- Other stuff I forgot right now

The system powers the knowledge base of my recent app "InSite" for web
developers: [https://www.insite-feedback.com/en/help](https://www.insite-
feedback.com/en/help)

You can see it also in action working - with a different theme - for my
javascript UI library "modoJS":
[http://docs.modojs.com](http://docs.modojs.com)

That page is a bit more complex. It does _not_ use multiple languages there
but it makes great use of the reference pages and has many many editable live-
demos. It also has some custom modules like a live build script for the
javascript library. At one point it even had a complete user-module with
payments but I disabled that when modoJS went opensource.

Another instance of docEngine runs for my pet html5 game engine:
[http://wearekiss.com/gamekit](http://wearekiss.com/gamekit) This one uses the
default theme, has most pages in two languages and again incorporates a couple
of live demos.

I host a little documentation about the engine itself here, but its not
complete right now:
[http://wearekiss.com/docEngine](http://wearekiss.com/docEngine) You can also
find the github link to the project in the footer of every hosted
documentation.

Have fun with it - I give it away for free. Critics and comments welcome!
Everything I have linked was built by myself.

------
ericclemmons
Trying something new on this month's project: "developer first experience".

Besides the README.md to get started, the app defaults to a private portal
with a component playground (for React), internal docs (for answering "how do
I"), and tools for completely removing the need for doc pages at all.

I believe that documentation has to be part of the workflow, so component
documentation should be visible while working on the component, tools for
workflow should have introductions and helpful hints rather than being just
forms and buttons, etc.

So far, this is proving fruitful.

(Side note: wikis are where docs go to die.)

~~~
brwr
Thanks for the reply!

Two questions for you:

1) I agree that documentation has to be a visible part of the workflow, but
getting buy-in from the whole team is difficult even with small decisions.
What have you done to get your team onboard with writing docs?

2) Why are wikis where docs go to die?

~~~
davidjnelson
2) perhaps because it's hard to find what you're looking for, and for code
they are almost immediately out of date, so why bother. I find getting
collaborators subscribed to email updates for changes helps with this problem.

------
intrasight
The first software system that I worked on was the operator consoles for a
nuclear power plant. A two year long dev project. We used Framemaker (1990,
before Adobe purchased them). Was an awesome tool for technical documentation.
Our documentation when printed and bound was three feet wide on a shelf. I
think I contributed two inches. It's been all downhill since - both in terms
of the tools and the quality of the documentation. Now days it's the typical -
auto-gen from code plus markdown for narrative.

~~~
jes
I totally get that. I also used FrameMaker back then. It was really a nice
tool for technical documentation.

------
angersock
Long ago I learned to love wikis. Mediawiki, Dokuwiki (easy to set up), or
Confluence. Hardest part is to keep people from just throwing garbage
everywhere--if that happens, people stop referring to the docs, and the system
collapses.

The important thing about docs is to keep in mind the audience. This is
important because it lets you estimate their mental model and omit things that
are redundant: for example, if it's internal documentation for a codebase,
there is little need to explicitly list out Doxygen or JSDoc style
information, because they have access to the damned source code. External
audiences may need certain terms clarified, or some things explained more
carefully because they _can 't_ just read the source.

I'd say that the biggest thing missing in the documentation efforts I've seen
fail is the lack of explanation for the overarching vision/cohesive
architecture of the work. This is sometimes because there _isn 't_ a single
vision, or because the person who has the vision gets distracted snarfing on
details that are not helpful without a preexisting schema to hang them on when
learning. So, always always always have a high-level document that describes
the general engineering problem the project solves, the main business
constraints on that solution, and a rough sketch of how the problem is solved.

Ideally, the loss of the codebase should be less of a setback than the loss of
the doc.

I will say that, as your documentation improves, you will hate your project
more and more--this is the nature of the beast as you drag yourself through
the broken shards of your teams engineering.

~~~
brwr
Thanks for the insight!

Regarding documentation covering an overarching vision for the code: It is my
experience that the person best-suited to write these docs -- i.e. The person
who knows the codebase the best -- is always in demand at the company. This
person has very little free time and I doubt they want to spent it writing
docs for everyone else.

Is that something you've noticed?

~~~
angersock
Yep.

The thing is, the company needs to understand that the smartest thing to do is
to leave that person alone and task them on educating (here via docs, but also
in other ways) the other developers (assuming the team is of sufficient size,
which in my experience is the case as soon as total headcount is 3).

Hoarding expertise like that is a good way to waste company resources (because
other devs function at a great disadvantage) and to bring down stress upon
onself (becuase you become a bottleneck and that gets to be super stressful).

The fact of the matter is that it is anti-social and bad practice for these
devs not to take a step back and write down the coherent vision of their
product--and if they can't explain the vision in a handful of pages with some
simple diagrams, _they 've probably deeply fucked up the design_.

The company, management usually, needs to bite the bullet and sacrifice short-
term firefighting ability for mid-to-long-term training.

If they won't do this, you should leave.

~~~
brwr
What you described is what I'm hoping to see over the next few months. I
joined the company recently, so there's still a lot of internals that I don't
fully understand.

------
kenOfYugen
I enjoy Literate CoffeeScript and that's where I picked up the concept of
Literate coding.

I believe that literate style of code writing has many benefits in any
language.

Basically mix markdown with the codebase and export the documentation from the
same file.

For a very well executed and interactive example check out

[http://dave.kinkead.com.au/modelling-the-boundary-
problem/](http://dave.kinkead.com.au/modelling-the-boundary-problem/)

------
someguydave
Our APIs are documented with comments that Sphinx uses to generate HTML
documents. Unfortunately, all of our other documentation is written in
Microsoft products because "that's what people use"

~~~
brwr
Sadface. :(

I know your feels. I've worked at companies that do things because "that's
what people use". Never fun.

What sort of documentation do you and your team maintain other than your API
docs?

Also: +1 for Sphinx! <3 ReST

------
mixmastamyk
Sphinx or mkdocs:

[http://www.sphinx-doc.org/en/latest/](http://www.sphinx-doc.org/en/latest/)

[http://www.mkdocs.org/](http://www.mkdocs.org/)

Which make it easy to create html, pdf, epub, latex formats, etc.

I like to create a user guide, developer guide, and ops guide for each large
project.

------
NearAP
We have technical writers who work in conjunction with developers to author
the documentation. I don't know what tool they use. However, since you say you
want to get better at writing docs, let me offer some perspectives based on a
user of documentation.

1) Write to all of your target audience. For example if your product is
targeted at both technical and non-technical people, then write the
documentation in such a way that non-technical folks can understand it. Don't
just write for the technical people.

2) If possible, write documentation around several 'how do I do XYZ task'? My
experience has been that people tend to turn to documentation when they want
to execute a specific task and they tend to search for those phrases

3) As much as is possible, include examples. This tends to remove ambiguities.

~~~
brwr
That's really good advice.

I also want to add a ton of documentation around the "Why?" factor. Why did we
make this decision? Why are we using this technology? etc.

The first question is always "How do I do this?". The second question is
almost always "Why do I have to do it that way?". ;)

------
buremba
We use Swagger specification (automatically generated using annotations in
Java) and generate Slate documentation from Swagger specification for API
documentation. ([https://api.rakam.io/](https://api.rakam.io/)). We also use
markdown for generic (tutorials, technical etc.) documentation and render the
markdown files fetched from Github in documentation page using JS. Since
everything is dynamic, we don't need to worry about updating the documentation
page, we just update README files of repositories, add documents to our
documentation repository and the documentation page is always up-to-date.
([https://rakam.io/doc/](https://rakam.io/doc/)).

------
nahtnam
Elixir has a __great __documentation system built in. I use that.

------
drygh
At Ionic, we use Dgeni
([https://github.com/angular/dgeni](https://github.com/angular/dgeni)) for API
docs. We have a few custom build tasks that allow us to version the API docs.

We also have higher level documentation, which is meant to serve as a sort of
conceptual overview of the framework, as well as to show what the framework
comes with out of the box. This section is written mostly in kramdown, which
gets parsed by jekyll before it's turned into HTML.

------
Tharkun
Most of our documentation attention goes towards the user manual and the
system operator manual.

We generate the bulk of those manuals based on our object model, which is
liberally sprinkled with (text only) descriptions. We've created a simple XML-
based authoring framework which allows us to create pretty tidy documentation.
Including images, tables, code examples etc.

We convert that XML to Apache FOP. At the end of the process, we're left with
a bunch of tidy PDF manuals in a variety of languages.

------
gravypod
The thing that has always guided me right is that you need to a) split up
functions, b) document method headers in every case with a short description
of what it does, and finally c) come back one month later and rewrite any
documentation that does not make sense.

This is the most important step. If you cannot remember it from a blank slate,
then no one can. Keep doing that until you understand the code at first
glance. Then your code will be easy for anyone to maintain.

------
mixedCase
A mardown-based wiki under version control and code comments. Everything else
likely isn't worth docummenting or just merits direct person-to-person
communication.

~~~
brwr
What do you keep in the Wiki?

~~~
mixedCase
Deployment details, how to set up test environments, graphical design stuff
(e.g.: how to use logo and its palette hex codes, reasoning for some UX
decisions, etc), ideas to discuss for major versions... Pretty much everything
that needs to be written down and isn't public facing or should remain private
to certain positions.

------
scottlocklin
LaTeX. We have academic roots, it works with source control, and the output
looks fantastico.

~~~
MattF
We chose LaTeX too for those exact reasons plus:

* macros allow us to produce integration-specific installation and user guides

* ability to generate HTML and PDF versions

Lately though I'm beginning to regret this choice. The owner of the docs isn't
allowed to commit to our repo (for good reason), but this means I get changes
via the wiki which need to be cut and pasted in. Also, the HTML output was
never really good enough, so we've stopped doing that. Getting long tables to
look good takes a lot of rebuild-and-check cycles. But my biggest issue is
that having a common source for each document with minor version-specific
changes sounds great until you try to adjust the page breaks. What looks good
for one doc looks bad for another, it's a real nightmare.

------
kakwa_
At work, I've seen a variety of solutions, depending on the teams I work with:

* MS doc(x) on a network folder with an excel spreadsheet to keep track of docs (and a lot of ugly macros).

* MS doc(x) in a badly organized subversion repository (side note here, docs comments and revision mode are heavily used in those contexts, which is really annoying)

* rst + sphinx documentation in a repository to generate various outputs (html, odt, pdf...) depending on the client.

In some cases we also use Mako (a python template engin) before sphinx to
instantiate the documentation for a specific platform (ex: Windows, RedHat,
Debian...), with just a few "if" conditions (sphinx could do it in theory, but
it's quite buggy and limited).

I've also put in place a continuous build system (just an ugly shell script)
rebuilding the sphinx html version every commit (it's our "badly implemented
readthedocs.org", but it's good enough for our needs).

In other cases we use specification tools like PowerAMC or Eclipse/EMF/CDO
based solutions, the specification tool in that case works on a model, and can
generate various outputs (docx, pdf, rtf, html...).

At home, for my personal projects, I use rst + sphinx + readthedocs, or if the
documentation is simple, just a simple README.md at the root of my repository.

As a personal opinion, I like to keep the documentation close to the code, but
not too close.

For example, I find it really annoying when the sole documentation is doxygene
(or equivalent), it's necessary to document each public methods/attributes
individually, but it's not sufficient, you need to have a "bigger picture
documentation" on how stuff works together (software and system architecture)
in most cases.

On the other side, keeping the documentation away from the code (in a wiki or
worst) doesn't work that well either, it's nearly a guaranty that
documentation will be out of date soon, if it's not already the case.

I found having a doc directory in the source code repository a nice middle
ground.

I found wikis annoying in most cases, rarely up to date, badly organized and
difficult to version coherently and properly (ex: having version of the doc
matching the software version).

------
tamersalama
This question is on my mind too. My clients documentations are usually a mix
of MS Word & Visio. Lots of repetition and gunk in between.

Ideally, I'd love to find a mechanism that:

    
    
      - provides the OO principles in documents; Encapsulations, Abstraction, Polymorphism, Inheritance .
      - Accessible & maintainable by non-techies.
      - Allows scripting (I toyed with PlantUML, but it was a bit rigid).

~~~
brwr
One of the requirements we're facing internally is having a system that can be
used by the entire company and not just the engineering team. Unfortunately,
the options that have been presented are all wikis with poor UI. :(

------
afarrell
Not on a team, but I used mkdocs for this tutorial I built, then added a
comment system that I built with react.js : [https://amfarrell.com/saltstack-
from-scratch/](https://amfarrell.com/saltstack-from-scratch/) The advantage of
mkdocs is that it is markdown-based so it is super easy to get started.

~~~
brwr
What makes Mkdocs easy to get started? I'm not familiar with it, so any
insight you have is great. We need something that requires minimal commitment
from the team, you know?

~~~
afarrell
\- It is markdown, so users probably already know the syntax and can just
write plain text files.

\- Installation just requires a pip install

\- You can view the generated docs with `mkdocs serve`

\- It comes with nice-looking themes, such as the readthedocs theme.

\- You can deploy it to a static site host by just copying the site/ directory
to your host.

------
acesubido
Gitbook for Technical Documents, Google Drive for everything else.

~~~
brwr
That's really interesting. Wasn't expecting to hear Gitbook. Why Githbook?

~~~
tdvorak
Another Gitbook user here. For me, it's the simple markdown syntax, nice diffs
in GIT/SVN, tooling, exports to HTML/PDF with plugin possibilities and minimal
vendor lock-in.

That said, the preferred tool in our company is still MS Word. Fortunately
I've managed to adapt Gitbook output to look pretty much the same as output
from our Word template.

~~~
brwr
Is your company using the Office 365 version of MS Word? I wonder if it would
be possible to automatically convert an MS Word file to Markdown :o

~~~
tdvorak
Not sure about the version, but probably 2013. Maybe Pandoc could help you
with the conversion.

------
ddasayon
We write the docs as markdown files and then use Doxygen to compile it to html
and LaTeX for the traditional folks who MUST have a printable document. The
markdown files are tracked on Git so that we can collaborate and track easily.

~~~
ddasayon
We use Swagger too, but we havent figured out how to take output from Swagger
and integrate it into Doxygen.

------
darkFunction
Bitbucket's wiki on our project page (6-person startup). We document mostly
application behaviour for technical users of the app (server team, content
writers) and a little bit of architecture if the complexity warrants it.

~~~
brwr
Does Bitbucket's wiki support search? Github's doesn't and thats one reason it
was vetoed.

------
hooliganpete
I work at a very large company so you won't be surprised to hear we use a
variety of tools and there's often overlap. Almost everything goes to
Confluence (our program wiki) including tech specs and marketing
documentation. The product team often uses something simple, such as Quip to
store and collaborate on their docs. Marketing tends to migrate toward Drive.
I think the best advice I can offer is to keep one "source of truth". This
isn't too difficult when your team is small but as you start to grow, having
one place devs, marketing, sales can go really helps streamline things.

------
girzel
The Texinfo format, using the in-Emacs Info browser. Yes, it means you only
read your documentation inside Emacs, but it's hands-down the best doc-
browsing experience I've ever had. Hell to write, butter to read.

------
rusbus
Shameless plug: I'm working on a documentation solution for dev teams. You can
sign up for the beta at [http://docily.com/](http://docily.com/)

~~~
brwr
Hey! Docily sounds cool, but we've already vetoed a few options because we
want our documentation de-coupled from our codebase. We want the entire
company (not just product and engineering) to be able to use the system we go
with.

------
MalcolmDiggs
We tend to thoroughly document our API (which is the backend behind our mobile
apps and website) using ApiDocJs.com or Swagger.io/swagger-ui Every service
and method is thoroughly explained in detail so the front-end folks have a
reference to work off of.

The rest of the systems are documented ad-hoc. Some readme files here and
there, a large block of comments inside of confusing files, the occasional
style guide, etc.

We also have an onboarding guide for new devs (just a PDF) which walks them
through our systems, our tools, etc. Nothing fancy, about 10 pages.

------
tmaly
This is a problem I am struggling with right now.

I have a CVS repository of PDF and Word docs.

The business side uses docx format, so using markdown and generating docx is
not really feasible. I have run into issues of people changing the filename
and it creating a new entry in the version control. I have a idea I plan to
implement to fix this.

What I would really like is some linux system that would make it easy to pull
the text out of docx and make it searchable. I would want something that could
run on the command line that does not have a ton of dependencies.

------
quasiben
All of folks at Continuum Analytics use sphinx and readthedocs

------
mbrock
We barely have any documentation except some READMEs that are mostly terse and
still poorly maintained... If you don't understand something, you ask someone.

~~~
brwr
It's not a bad solution, unless you're the guy who knows everything. And I
don't mean that in a facetious way; some companies have one person that knows
everything about the codebase. We've got one of those guys on our team. I
think he sometimes gets sick of answering noob questions, because we've been
growing like wildfire over the past 6 months.

~~~
mbrock
Yeah, because documentation has its own costs.

I've been thinking about setting up a forum. That's a flexible form and might
encourage creating the documentation that actually answers real questions.

------
davidjnelson
The most valuable docs for me are rest Api contracts stored in confluence.
Easy to collaborate on. Also, getting started guides in confluence for new
hires, and architectural diagrams again in confluence for cross team
collaboration / understanding / discussion.

As for code, auto generated docs from jsdoc etc. headers are fine but I never
use them honestly. I find unit tests to be the ultimate documentation in terms
of code level docs.

------
gault8121
HN, we are writing our high level overviews as Readme MD files. Any ideas on
how we could help condense this info for open source contributors?

------
adnanh
We wrote our custom documentation generator for Grape (ruby), something like
Swagger, but less rigid.

------
BooneJS
Adobe FrameMaker and Microsoft Visio, stored in Perforce.

Beautiful documents, but it takes a decent chunk of time to create. We do
extract some docs via XML to generate code, somewhat backwards from how most
engineers merge docs and code.

------
irixusr
I work for the government right now.

I'm trying to gather a community of git supporters to push for git.

However, after three months I still haven't gotten a computer suitable for my
job.

------
arisAlexis
My boss decided to use Framemaker with DITA in 2016..

~~~
jlengrand
My friend. I ctrl + f through the page to see if someone was just as
infortunate as I am :).

We are using DITA as well, in a 10 people company. Because it is so much fun
to go through XML right ?

The genius in DITa, I think, is that the guys behind it have basically created
a market by themselves. I mean, the main reason we don't get off it today is
because we had to hire an expert long time ago to get our layout done, and we
don't want to have to redo it.

Sad times :).

------
zolokar
A combination of Github Wikis and a Dozuki site.

------
barile
swagger.io for the apis + README.md on each service's repo

------
adityar
doxygen

------
douche
Fucking Word docs. Which are checked into source control, except people (who
are nominally developers, or project managers who were supposed to have been
developers once) insist on versioning in ye olde rename-and-add-a-number
style. With PDFs that are manually generated by exporting said Word documents
from Word, and then again checked in, and again checked in in multiple renamed
versions. Except sometimes only the PDF is checked in, without the source
document...

So we have a doc folder in the repo that is like staring into the maw of
Cthulhu and takes up 90% of our build time on the CI server sucking that down
mass of garbage for the checkout.

Saner systems have been proposed, but rejected because the powers that be are
too averse to change...

~~~
thorin
I used to see this all the time. No comments on the checkin either. Also the
managers that would say I don't know how to access cvs/svn/git can you put it
on a shared drive for me...

------
vacri
We used to use a Mediawiki wiki, which only I would edit. You kind of have to
be comfortable with mediawiki syntax (does the job for everything but tables,
which suck). So we moved to Confluence, which has a WYSIWYG editor, to
encourage more people to document things, upload documents, so on and so
forth. Again, I am the only one editing it... so our documentation is "very
occasionally write something down, and store it on your laptop or in your
private google drive, then spend ages searching for it when someone asks".

So whenever a new staffer comes along, I get asked to give them wiki access...
but I'm the only one here that uses my edits (only ops staffer). Sure, have
some wiki access, for all the good it will do you!

I really don't recommend our model :)

Anyway, this is an important point: _documentation is not free_. It takes
time. Even shitty documentation takes time. If you want good documentation,
you need to budget time away from other tasks. When I used to work in support,
the field repair engineers would budget 30% of their hours for doing paperwork
- not _documentation_ specifically, but it clearly shows that 'writing stuff'
is not something that springs as a natural/free parallel to other activity.

~~~
brwr
We've already have internal discussions about whether it makes sense to make
documentation part of our ticketing system (we use Pivotal Tracker). Everyone
seems to agree that it's the only way the docs will ever get updated. 30% is a
lot though!

~~~
vacri
30% is for field repair support guys, who have to fill out full paperwork on
every single job (and it's a rule of thumb, not ironclad). Not every software
ticket requires that. It's just more to show that documentation requires some
time; it's not something that you "just spend +5 minutes on the task and it's
there". Minor edits, sure, but not good documentation.

------
DannoHung
Related: what's the right way to extract inline comments regarding function
API stuff from source code?

This seems like something that is a really good idea, but is hard to find any
projects for it.

~~~
jack9
I remember reading about failed experiments from the 90's to separate inline
comments from source code through a form of duplication. Mark a "source"
folder and a "documentation" folder. Every time you open a file in the source
folder structure, create a duplicate file in the documentation folder
structure (including folders and nesting). Comments are expandable blocks with
markers for start and end of code that they apply to in a side-by-side pane.
Viola, inline comments without inline cruft. Version it all and you're good to
go. When I have time, I will try to recreate it as an IDE plugin for
someone...when I have time.

