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
  • 1
    Your 2nd paragraph sounds like it's a hell of a lot better than I have seen in many organisations – Mark Henderson Mar 22 '16 at 14:33
  • Well...that's just terrifying. – mlw4428 Mar 22 '16 at 14:35
  • 1
    The fact that you have _something_ written down is better than a lot of places. Sometimes that's deliberate (so people can retain their tacit domain knowledge, thinking it will enhance their job security). Sometimes it's laziness, sometimes it's incompetence. – Mark Henderson Mar 22 '16 at 14:39
  • 2
    There are a number of ISO standards for technical documentation, as listed on [en.wikipedia.org/wiki/Technical_documentation](https://en.wikipedia.org/wiki/Technical_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. For software: https://en.wikipedia.org/wiki/IEEE_12207 also governs documentation – HBruijn Mar 22 '16 at 15:28
  • Well, in my experience binary formats for textual documentation are infuriating within about 5-10 years of their creation. With the possible exception of PDFs. You don't want someone today to be unable to open an SOP because it was written in 2003 using the 1997 version of WordPerfect, and you don't want someone a decade from now looking at a file with a `.docx` extension and thinking "well, figuring out what this contains will be- minimum- the next five hours of my life". – Parthian Shot Mar 22 '16 at 15:50

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
  • 72,524
  • 21
  • 127
  • 192
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
  • 16,472
  • 3
  • 40
  • 59
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
  • 7