Ask HN: How does your team write documentation? What tools do you use? | Hacker News Reader

Ask HN: How does your team write documentation? What tools do you use?

77 pointsbrwr90 comments

We're trying to get better at writing docs, so I thought I'd turn to you guys for help.

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?

View on HN

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.

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.

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/

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

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

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

That looks awesome, thanks for sharing! Had a chance to talk to some Exosite people here in Taiwan, very impressed on all level! :)

Wonderful! Thanks for the kind words.

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

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.

I'd definitely be interested. :)

See also TiddlyWiki, a full wiki with search, i18n, plugins, etc and which gets stored in a single .html file.

http://tiddlywiki.com/

It occurs to me that I didn't really answer the question as it was being asked, I blame it being after midnight when I wrote that (and being too excited about showing off my search thing).

We do have the technical part down pretty well, but actually managing the documentation is one area that we're still lacking in. For the longest time our docs consisted mostly of just an API reference [1] and to be honest that did really cover about 90% of the needs of our customers, but that last 10% involved quite a bit of hands-on coaching with most of our customers to get them to understand the system as a whole before they could go off on their own and understand which API calls they'd need to make to do the thing they wanted to do.

One of the biggest helps has been keeping everything in github. Having all the docs be markdown is great because it's just text so everyone can use the tools they want to, we're not locked into some web wysiyg editor. And since it's all in git it's trivial for anyone in the company to open an issue about something incorrect or even submit a PR for anyone that's more technical. Plus when someone does have a question that I and the other editors don't know the answer to we can just git blame it to find out who put the piece in question there and ask them to clarify what they meant.

Now that we've been able to grow so much we're getting more able to focus on polishing up the docs, which is actually officially my job now that I've moved from the support team into the (new) technical marketing team. We've started making more information that describes how the system works as a whole [2] so that we can have completely hands-off customers who just pay us money without us having to personally walk them through the system.

Of course there are other fun things that I intend to do with it like interactive demo API requests and auto generating a table of contents, but those are really just 'wizz-bang' features that are fun and helpful but are definitely not required.

These are some of the other sites that I've taken (or am planning to take) inspiration from: [3] [4] [5]

[1] http://docs.exosite.com/rpc/

[2] http://docs.exosite.com/oneplatform/

[3] http://developer.wordnik.com/docs

[4] https://www.twilio.com/docs/

[5] https://docs.particle.io/

We use flatdoc and Swagger UI for building docs, like: 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

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

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/

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.

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 It works out pretty well for them with no big trouble, and they literally let everyone change things (not just project members).

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

You can see it also in action working - with a different theme - for my javascript UI library "modoJS": 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 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 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.

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

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?

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.

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.

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

These stories just make me more and more sad. Haha. What are you using these days?

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.

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?

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.

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.

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/

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"

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

Sphinx or mkdocs:

http://www.sphinx-doc.org/en/latest/

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.

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.

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?". ;)

We use Swagger specification (automatically generated using annotations in Java) and generate Slate documentation from Swagger specification for API documentation. (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/).

Elixir has a great documentation system built in. I use that.

At Ionic, we use 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.

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.

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.

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.

What do you keep in the Wiki?

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.

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

You're way more hardcore than I am. I tried LaTeX once. I still have scars.

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.

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

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

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. :(

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/ The advantage of mkdocs is that it is markdown-based so it is super easy to get started.

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?

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

Gitbook for Technical Documents, Google Drive for everything else.

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

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.

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

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

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.

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

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.

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

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.

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.

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

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.

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.

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.

All of folks at Continuum Analytics use sphinx and readthedocs

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.

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.

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.

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.

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?

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

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.

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.

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

We're hiring? :)

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 :).

We are 100% unstructured!

A combination of Github Wikis and a Dozuki site.

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

doxygen

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

I feel like you need a hug. :( That sounds absolutely terrible!

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

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.

Those mediawiki tables...

Wikis seem like such a great idea, but I've never seen an implementation that was good enough and low friction enough that people will actually use them. Same for Sharepoint...

We use MediaWiki + SMW / Semantic Forms. This allows to define a data model and forms which makes it easy for user to add / write to the wiki in a structured way - and without sitting before a blank page. For free text, the new Visual Editor works also rather well, though it's not easy to setup.

The structured information can also be queried, visualized, exported to various data formets etc.

To document software projects, I really like to write *executable documentation". E.g. I'm using JSON Schema a lot to define my expected data structures and contracts between modules.

Then I write a small program that automatically generates the technical documentation based for me. Humans can still add/annotate to the documentation because it's a wiki (and I can separate between auto-generated and human-generated rather easily, because of queries).

So far, I really like this approach as it has the automation of doc generators, the flexibility of wikis. Most of the information is stored/accessible as data / API. The downside of this appraoch is, that this platform takes some time and knowledge to setup and model the data structure / forms. Without those, corporate wikis usually seem to die the "one man show" death you described

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!

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.

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.

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.

I've thought about this a bit and personally came to the conclusion that extracting inline comments is a bad idea. They are inline for a reason.

By way of example, I frequently use inline comments to discuss things like how a given class is architected, which (if any) popular design patterns are used, usage examples, etc. This stuff is really only relevant when you have the file open in your editor, so inlining the comments makes perfect sense.

Reply on news.ycombinator.com