-6

I've been promoted in my company's IT department, we have 3 developers, a DBA and a Sys Admin. and one of the first major projects I want to tackle is updating how we manage our department's Documentation. Basically, it can stand to be a lot more organized. Each member has some documents they manage for the job, but basically there is a lot of "one hand doesn't know what the other is doing". In addition, there are a lot of incomplete and/or outdated documents spread across a number of directories in our shared network drive. New technology is not well documented, etc.

So a few questions I have is:

Is there any specific software that's recommended for centralizing documentation? For example, I have heard some people use Media Wiki.

Any advice on an organizational structure for documentation?

Best practices for dev team documentation?


Worth mentioning that our company is a .NET shop.

(Also, If these questions seemed open ended, or not constructive, I apologize. I'm happy to get any personal accounts, but even just a few quick tips based on your experience, would be really helpful.)

closed as off topic by ChrisF, yannis, IDrinkandIKnowThings, jcmeloni Jun 22 '12 at 14:47

Questions on The Workplace Stack Exchange are expected to relate to the workplace within the scope defined by the community. Consider editing the question or leaving comments for improvement if you believe the question can be reworded to fit within the scope. Read more about reopening questions here. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 1
    This is probably a better question for Server fault or Super User... maybe programmers but this is a bout work function not workplace. Its off topic. – IDrinkandIKnowThings Jun 22 '12 at 14:32
  • 4
    Hi kdub and welcome to The Workplace SE! Your question has been closed as off-topic because it is more about processes within work functions (as @Chad said) and not the workplace. If you focused your question and made it less of a "shopping" or "polling" question, it could find a home at Project Management SE but please check their FAQ first. Thanks! – jcmeloni Jun 22 '12 at 14:50
  • @jcmeloni, I appreciate you letting me know. Is there anyway going forward, that instead of down voting and question closing, that you can redirect the question to the proper stack exchange. I think it's pretty obvious that because it's my FIRST post, that I didn't know it was a question that was off topic. To me, Workplace seemed the most appropriate for suggestions on handling documentation in the workplace. It was my mistake and I apologize for that, but I don't think down votes and closed questions are the appropriate response for simple confusion. – kdub Jun 22 '12 at 14:56
  • @Chad, thank you for your understanding and informing me of a more appropriate stack exchange to ask my question. That is a helpful solution. – kdub Jun 22 '12 at 14:58
  • 4
    @kdub Actually, downvotes and closed questions are how the StackExchange system works overall. When questions are flagged and downvoted, the moderators discuss possibilities for migration with other moderators (of the other sites), if the question seems like it could be a fit elsewhere. If a question isn't migrated directly, like yours was not, it means that no other site mods wanted it to be automatically migrated because it didn't meet the requirements in their FAQs. – jcmeloni Jun 22 '12 at 15:12
3

My company (300+ people) uses what you probably already have: OneNote.

There's a network share and we have a few shared OneNote docs that are located there. You can create workbooks, sections for different tasks/etc and pages within them as you normally would. You can link to all other kinds of things in a onenote doc and it can be worked on by numerous people at the same time. It's actually a pretty good solution and it's easy to maintain (ie. as per IT, they just keep the server on and never have to do anything else).

For organization:

  • Our first workbook is the rampup document for new hires. It outlines basically everything that a new hire will need to know in their first 2 weeks
    • Step-by-step configuration of their environment, managing their IT resources, contact info for who to contact about certain kinds of things; that kind of info.
  • Our second workbook is for instructions/guides for using some of the more complicate software that we have (detailed instructions for setting up and configuring multi-tier sql server + sharepoint + biztalk + etc. environments in multiple languages for certain special cases that we have).
  • We create other workbooks for special/proof of concept/research projects (in the beginning it's a bit of a knowledge dump, but then once the PoC/whatever is starting to materialize and more resources get put on the project, the doc is organized to flow a bit better.

That's roughly how it's laid out. There's certain people on the team who take better care of it than others, as they're more apt to do it, and they're recognized for that contribution as it generally hinders their direct task productivity sometimes, but contributes to everyone else's task productivity. I think this is important to recognize.

3

We use Sharepoint. We have a place for documents to be uploaded (especially documents like Requirements that will be provided to the client) and sorted by type of document. We have a Wiki where we keep less formal information such as code snippets and advice about where to find various things or discussions of how to to common tasks. We also have a team calendar in there that is linked to our team Outlook calendar. OUr wiki is even set up to have an email address, so if you write some snippet to a junior developer to help them with an issue, it can go to the Wiki automatically just by making the wiki email address a copy to on the email.

The actual tool isn't as important as being organized and having a standard set of expectations. We are organized by team and client and that is how our Sharepoint is organized. We have standard formats for required project documentation, so that everyone knows exactly what they have to produce and producing the documentation is one of the things we are evaluated on (and all projects include time for documentation in the Project plan and the Hour estimate that the client approves), so people will do it.

  • You don't even need a Sharepoint website. All you need is a single network location, where ALL files will be located, just don't give people an option ( i.e. take away the current location after a migration to the new system takes place ). – Ramhound Jun 22 '12 at 13:47
  • @Ramhound, I agree Sharepoint isn;t necessary that;s why I said the tool wasn;t as important as being organizaed and havign standard expectations around documentation. And I didn't emphasize it but having hours available in the project plan to do documentation is critical - no hours, no documentation. – HLGEM Jun 22 '12 at 14:03

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