I'm working on the creation of a software and product documentation in a wiki format. It will include the documentation for all the company products.

After some research, we decided to use the MediaWiki platform and create a private wiki accessible from our internal network.

This documentation will include mainly software artifacts for now:

  • Database Diagrams;
  • Data Dictionary with database meta-data;
  • Short description of the product;

In the future, it will also include:

  • UML artifacts and diagrams;
  • Use cases;
  • Help pages for support team;
  • Bug reports;
  • Statistics information around the product;
  • Test guides;

The wiki structure is not a problem, but my first thought was block some pages to some specific users. Apparently, that's not possible using MediaWiki, so anyone in our internal network will can visualize all the documentation, although they can not edit.

My question is: Are there any problem in keep this documentation public for anyone in the company? I mean, the software docs are important for the developers and technical teams, but the sales team, for example, does not need to see all these pages, right? The statisthical data should be acessible fordevelopers? It should be public?

The documentation will not include any sensitive data, like keys or passwords, but I'd like to know if there some standard approach on the documentation access in large companies.

I found these similar questions here, but they are about code documentation and a discussion about the use of wikis for documentation, that is not my case.

Based on the comments, here are some updates:

I explained the whole picture, but I'm specially concerned about possible problems with unauthorized access to software documentation.

When I started the documentation project, I thought that hide some parts could be a good approach, but thinking (and searching) about it, I don't found a pattern.

So, my question is about any standard (or recommended) approach used by software engineers to deal with (internal) software documentation. Are there any?

  • 2
    Other than the fact that you are keeping software-related material on this wiki, I really don't see what it has to do with software engineering. This is a workplace culture question. – David Arno Nov 25 '16 at 14:30
  • Thanks for your comment @DavidArno. Maybe I'm in the wrong place, but I'm Interested in knowing how software engineers deal with the access control of the software documentation (maybe some standard approach used by software companies?). I explained the whole picture, but I'm specially concerned about possible problems with unauthorized access to software documentation. To me, its all about softwares docs, you see? I'll wait for more comments (or downvotes) before to migrate this question for workplace.se. – James Nov 25 '16 at 15:03
  • 3
    Where do you see any benefit in hiding information from people? If they aren't trustworthy, you already have bigger problems. Otherwise, it's just going to be an inconvenience for everybody whenever the project team changes. – Simon B Nov 25 '16 at 15:28
  • Thanks for your comment @SimonB. This is exactly my question. When the documentation project starts, I thought that hide some parts could be a good approach (to developers what's for developers). When I found that MediaWiki limitation I started to think about and now I want to know if we have any standard (or even recommended) approach to deal with access-control in software documentation. I'll try to edit my question to make it more clear – James Nov 25 '16 at 15:58

I prefer an open to all model for that medium. For private sections put them in different mediums.

In this context I would say read access to all. Limit write access by section/group.

I think the argument for this approach are:

  • less infrastructure to maintain
  • people tend to not spend much time in areas they don't understand ' aren't interested in anyway
  • encourages sharing of information without needing to spend time classifying it for security

What I do distinguish is what actually goes where (which 'medium'), for instance it takes effort to make sure that:

  • Tthe wiki has up to date URLs
  • The code README file has relevant (to developers) installation information
  • The site has customer centric FAQ and Help pages
  • Passwords are - only - stored in a Password Manager (LastPass for our Company)

In general making documentation available to a larger set of people than need access to it isn't usually a problem. As it's unlikely to be invasive on their time and attention (you're presumably not intending to send out notifications to everyone that can access it) then it's harmless.

However, this assumes that the documentation does not contain anything sensitive.

Although I'm definitely not advocating this, I have seen internal documentation that contained details of testing and server accounts (including passwords!). If you need this sort of documentation then you could, for example, just give its location on a secured filesystem, or similar.

Similarly, I have seen internal documentation that has links to monitoring or data access tools. These may have different security requirements to the documentation proper. If they are independently permissioned then there is no issue but it's worth keeping an eye out for this sort of thing.

Particularly in smaller companies, it has been my experience that the use of security by obscurity is a thing (if no-one knows the URL then they won't use it). Obviously, linking something like this to widely available documentation could cause problems.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.