4

The organization I work for is a growing one and with that growth comes maturity and with that maturity comes a need to better document.

Today it's a hodge-podge of directories, wikis, OneNotes, and none of it is standardized in terms of form or content, labeling, or even knowledge of where to look for what item. Every team is different and even individuals on the teams don't necessarily adhere to any team standard.

I'm not looking for specific products or advice on what to standardize. I'm also more interested in what standards larger organizations/enterprises are using.

mlw4428
  • 159

3 Answers3

2

There are a number of ISO standards for technical documentation, as listed on en.wikipedia.org/wiki/Technical_documentation. The Wikipedia article implies that those are specific to certain industries though (and the actual ISO standards are not easily available in the public domain AFAIK)...

For software development for instance IEEE 12207 also governs documentation.

But the whole thing with internal documentation is that quite often most organisations want to do whatever specifically works for them, rather than following external standards.

Before trying to enforce a standard you're already quite ahead of the curve if and when:

  • documentation is actually generated
  • documentation is available to those who need it (it can be searched and found when the need arises and can then also be accessed...)
  • documentation is maintained and current

And as an IT department rather than trying to create and/or enforce any specific standards simply facilitate, for instancing by providing a good internal search engine

HBruijn
  • 84,206
  • 24
  • 145
  • 224
1

I don't know about any industry standards, but the best experience I've had with internal documentation was in an organization that had a dedicated team responsible for supporting and curating the documentation infrastrucure. But they were not responsible for writing all of the documentation themselves.

The system they used happened to be a wiki, but any single source of truth should work. I'd go so far as to say it should natively support versioning. There's nothing I can't stand more that people emailing around Word docs with multiple pages dedicated to a document changelog. If you need a copy of the current revision, it should be easy enough to export from the source as a PDF.

Most of the team had a tech writing background. They were responsible for developing templates for common documentation types. They'd help other teams get started writing their own docs. They'd audit the docs people were creating and potentially edit them for style/consistency. It was glorious.

And let's be honest, writing good documentation takes time and effort. There's no magic tool that makes it easy. The SMEs of a given system must be willing to write (and keep updated) documentation for their various systems/projects.

Ryan Bolger
  • 17,010
0

I can't speak as to particularly large organizations, but at most any size, coming up with a reasonably well organized standard, and enforcing it (within reason) so that all such documentation is on one platform, preferably one with access control and search capabilities is a huge step forward.

As far as legitimate standards and standard practice, I found this post detailing how you might develop your own, and what factors that might need to account for, as well as citing relevant ISO standards.

I believe that's all there is as far as defined standards, so then it just comes down to creating standards tailored to your organization's needs.

fusorx
  • 121