Ask MetaFilter questions tagged with documentation

I just want some answers!

soelo — Sun, 20 Dec 2009 08:47:23 -0800

How do I actually get the documentation that I have been asking for at work? I am already looking for a new job, so no need to give me that advice.

At work, there have been many new projects lately with lots of misunderstandings or just unclear directions from our supervisors. In a recent meeting, my first question was how often they wanted the data and they could not tell me weekly or monthly. We went forward assuming weekly, but there has still not been any specific answer.

I've been in this role for nine years, and two years ago our direct supervisor changed from one who required (and wrote) documentation for new projects to one who is much more laid back. This is when the smaller problems became much bigger. Most of these projects do not come from him, but from his boss or other people at that level in our department. I feel as if they know he won't stand up to them so they walk all over him, and by extension us.

In order to solve this problem, I have suggested that we use Sharepoint to document the details of projects. Other groups in our department use it, but my supervisor has ignored my suggestions. He has not said why, but I suspect he is afraid of learning new software. In the meantime, we still have these problems. When I have time, I can document some of my work and try to keep up with the new projects. But I have no training in documentation, plus we have a group who does the documentation for most of the other groups, but they don't support us.

I am not out to prove that we are always right. I know we make mistakes, but I am tired of seeing us blamed for anything that goes wrong. We feel scapegoated, like we are pawns in the sick game of office politics.

So, I'd like suggestions on how to get the documentation and clear answers that we need.

Not Actually Written By Dummies

lysdexic — Wed, 11 Feb 2009 12:44:54 -0800

I need help writing a detailed technical document in "for dummies" fashion. Is there a "for dummies" style guide as opposed to a style guide for dummies? We have a battered and tattered set of instructions for performing some major work on one of our critical systems. It has notes in the margins, things to look out for, and stuff we found in testing added to it.

The process went fine in the test system, but fell apart badly when we went to do it in production.

We know how we got there (i.e. what we messed up), and we're correcting it, but before we do this kind of procedure again, I want to re-write the instructions, with the annotations, in the "for dummies" format. I think the little icons (but wait!, techie info, danger!, etc) would be useful in these instructions.

Is there a "for dummies" style manual? My google-fu has failed me. I looked at this question, (plus the other ones that showed up as related) but I wanted to see what else was out there.

Advice on documentation tagging?

jethrographic — Tue, 11 Nov 2008 07:47:04 -0800

I am several weeks away from leaving my job for a new one. As a result, I need to document my current development efforts for the several folks who will be taking over my responsibilities. My challenge is how to organize documentation about individual components with some additional flexibility. I’m looking for a method, or software, that would allow a thorough initial organization of documentation notes, but also enable other slices or views: show me all bits that live on server X, show me all of the bits that support application Y, what applications depend on script Z, etc. This will be very light documentation – more of a roadmap covering where bits live and what they do broadly. I will continue with some transitional activities over the coming months to support deeper questions.

At a coarse level, I work on 3 types of components: data scripts, relational databases, and web GIS applications. I think these three areas make a nice basic framework for a thorough initial organization. However the pieces are intertwined in many other ways that my colleagues might need to know about – by application stack, by server, by project, by programming language etc.

I think some tagging of note elements is an answer, but not sure how to implement? We do use Trac and SVN, but I have been a bit slack about keeping all of my code there. I have also used FreeMind, but it doesn’t seem flexible enough. I have seen some ontology software that works like this (click an element and the word cloud reorganizes), but I’m not sure how ideal that is for notes. I could even make a word doc with tags, which is not dynamic, but still searchable.

Thanks for any and all suggestions…

I can haz Mozart too?

WidgetAlley — Tue, 23 Sep 2008 15:53:31 -0800

So, please help settle a dispute between myself and my boyfriend about Mozart and the musical capabilities of the average American. My boyfriend and I are having a bit of a row. He claims that the average Joe dragged off the street, who has no prior musical training, can hear part of a Mozart phrase and hear, in their head, where the phrase is going, having never heard the piece before.

I claim he is full of poop, and that the average Joe dragged of the street wouldn't know where a Mozart was headed [1] if you handed him the annotated score. Before I'll believe him, I require documentation or at least corroboration from a more reputable source.

[1] Obviously there are exceptions to that: if it is a very very strong leading tone, they may be able to tell that it shouldn't have stopped there, but not much else.

Opinions? Studies? Anything at all?

How does IT documenation work?

wabashbdw — Mon, 04 Aug 2008 11:53:34 -0800

Despite having no training whatsoever, I've gradually become 'the IT guy' at work. I want to get organized and begin building a documentation file but I have no idea where to start. Although there is a lot I don't know about technology, I am able to help people around the office with small computer problems. And when an issue is beyond my knowledge, I usually end up being a middle-man between the user and the company who handles our larger IT issues.

Well, my role as IT first-responder is growing and I need to get organized. My understanding is that 'documentation' is critical to an effective IT department, but I don't even know what 'documentation' means in this context.

So, what pieces of information are documented by most IT departments? Where/how is this information stored that makes it easy to find when it is needed? [For IT workers] What is your system for documentation and what would you keep/change if you were building a new system?

document my database

buttercup — Sun, 27 Apr 2008 18:58:45 -0800

I have a particular propriety database application that has a great feature for users to document notes and changes to the db. Annotated screenshot here. Basically, you click on the little yellow sticky note and the documentation window pops up and users can enter notes about changes, etc. Its so useful I would like to use it all the time. I am now creating a database project that I would like to recreate this documentation feature. I figured out the database structure for this by some creative sleuthing, but I am having trouble how how to link the documentation record to the particular field (and record) that it is documenting. For instance if I have a field in the table, Field1, and I have a button to pop up the documentation window next to that field, how do I automatically insert data into a 'reference field' into the documentation table that says this comes from Field1? I guess I can change the value of some variable and then automatically fill the field when data is entered into the documentation form.

Problem is, I am having trouble doing this in MS Access. Any ideas?

where are the docs?

tylermoody — Thu, 25 Oct 2007 12:43:52 -0800

How do I access the C documentation that's on my computer? I'm running OSX 10.4.10 with all the devtools installed. Whenever I want to use a header file or one of the standard functions that I'm not familiar with, I head to Google. I suspect that there are man pages for most everything that comes in a standard C environment, but how do I get to them?

Cliff-Notes for a Web Project

kaizen — Tue, 09 Oct 2007 13:59:00 -0800

I am looking for real-life documents surrounding the development of a website. My organization is quite inexperienced in building a website from scratch and we are looking for some documents to get us started. Can anyone point us to some actual specifications, wireframes, test scripts, and project plans for website design and development?

Wiki for Writing Books?

alms — Fri, 14 Sep 2007 09:23:49 -0800

Is there wiki software that is specifically designed for writing books? By "book" I mean a long piece of writing designed to be read from start to finish, possibly broken up into chapters, and possibly with a TOC at the start and index at the end. Every wiki tool I've seen is designed to allow authors to create websites i.e. non-linear and often relatively unstructured collections of pages. I want a tool that is specifically designed to allow multiple authors to work on a single linear text, possibly divided into sections and chapters. Of course, it should also support cross-references and other non-linear tools.

WikiBooks seems to accomplish this through a set of self-imposed style guidelines. I guess that works, but I'd rather have a tool that actually supported writing structured documents. The closest I've found is DokuWiki, which at least makes it natural to create a book, even if it doesn't enforce the structure. It would also be nice if this was an open source tool and if it supported standards (e.g. DocBook).

Does anything like this exist?

If it doesn't exist, I might write it. Think anyone else would want it?

Software Documentation

JPowers — Mon, 27 Aug 2007 08:24:57 -0800

I am a technical writer looking to improve my company's software manuals. I want to stay up to date with the latest technology documentation trends. Please leave comments on what you think some of the best manuals are for different software products and why. Basically, if you’ve ever read a software user manual and thought, “Wow! That was surprisingly easy to read…or helpful…or well organized…etc., then that is what we are looking for.

How to create one gigantic JavaDoc file?

Khalad — Mon, 09 Jul 2007 08:34:49 -0800

For-a-friend-filter: Help with JavaDoc. Hive mind, I need your help.

I have about 1,000 files of Java 1.5 source code that has been meticulously documented with javadoc tags. I can use the javadoc tool to produce about 1,000 pages of HTML documenting my code. Now what I really want is a way to generate a single document from the javadoc. The single document could be word, or PDF, or whatever. I’ve looked at Suns MifDoclet, but it doesn’t work with JDK 1.5. Help!!!

Should I trust passport expediting services?

Afroblanco — Tue, 01 May 2007 17:51:29 -0800

Are passport expediting services legit? I'll be traveling in less then a month, and, like a total dumbass, I've put off getting my passport. According to the USPS website, you can get your passport "expedited" for a $60 fee, and receive the document in a couple weeks. However, I found out today that they have a tremendous backlog, and expedited passports are now taking closer to 4 weeks. This is obviously cutting it a bit too close for comfort.

So, I do a google on US passports and all of these passport expediting services come up. Are these services legit? They promise to obtain a passport within days or weeks. This place is even a member of the Better Business Bureau.

The whole thing seems legit, but still, I wonder....

Software documentation

four panels — Wed, 31 Jan 2007 09:51:57 -0800

What's the best software for writing and publishing software documentation?

ISO Excellent/Innovative/Efficient/Fast/Cheap Document Management Software

owl — Mon, 22 Jan 2007 07:44:25 -0800

I'm looking for Document Management software along the lines of MediaWiki that is extremely user-friendly and FAST, but has more security options and more ability to control edits. I love the change-tracking, easy-linking, and web format of Wikipedia, but it is too difficult to restrict unauthorized changes to Documents in a large business environment.

Basically, I'm looking to initiate an Intranet Documentation library for use by about 400 people. The budget is about $30,000. We're talking Corporate Standard Operating Procedures, Corporate Forms, Etc., that require regular updates.

What options do I have?

How do I reorder visio pages in a long document?

mdiskin — Wed, 01 Nov 2006 09:21:03 -0800

How do I quickly reorder (multiple) pages in a very long visio document? Visio seems to assume that I create pages only sequentially and never move them around much. Actually my document will reach almost 200 pages, and I keep having to move them around and renumber them, or create new pages. How can I do this easily in a doc of this size?

Bonus points for helping me create a page that doesn't default position itself at the end of the document (which may be more my problem)....

Does my name remain the same?

TG_Plackenfatz — Tue, 05 Sep 2006 09:36:49 -0800

Have I successfully changed my name? So, I got married over a year ago in NYC. I opted not to change my name at that time, but recently decided that I would like to.

This morning, I went and got my name changed on my Social Security Card to my new desired name: "First Middle Maiden" is now "First Maiden Married." When I researched how to change my name on my Passport, it said all I'd need to do is send them my Marriage Certificate. And here's (what I'm afraid might be) the rub: my Marriage Certificate says "New Surname: Maiden."

It would seem to me that because of this, the Marriage Certificate doesn't really help certify that I've changed my name. I'm pretty sure I'd be okay at the DMV and with credit cards and the like by using the SS card, but might this cause problems? And if not with the Passport people, then might I eventually run into an issue? How else can I certify that I've changed my name, if I have indeed done so at all?

The programming is insubstantial, Catsby.

jacalata — Sun, 14 May 2006 07:54:24 -0800

What kind of documentation will convince a non-software guy that writing a program is actual work? I am in a semester long project group of four people, building a little electronic alarm. I'm the software engineer, the other three are all electrical students. One of them is pretty good (and knows some coding), but I feel that the other two group members aren't really very competent, either at the technical aspects or the teamwork. However, the issue is not in getting the project done, but in the peer evaluation rules for the end of semester. Three members of the team work together to assign a grade out of 15 to the other, and our individual assignment mark is modified by this evaluation.

My problem with this is that I have been pretty snarky about the way they're trying to run it and that I don't think they have any idea that I've done anything (software being fairly invisible). My attitude towards 'team meetings' and 'team work sessions' has degenerated (although this shows in my saying that we don't need to meet all day Saturday, rather than my not turning up when we do), because meetings turn into Competent Elec Guy explaining all the hardware to Incompetent Elec Guys, who treat meetings as a chance to do all the work they said they'd have done, and the incompetent guys are a liability when I'm debugging the hardware. I'm also terribly frustrated by their refusal (inability?) to use email as a means of actual communication, rather than a way to set up physical meetings and send me the agenda beforehand.

So, my question is: I'm trying to figure out ways of documenting all the software to show them I have been doing stuff; I have test programs ranging from 'check if we can output to pinB' to 'do everything!', and I've done up a graphical representation of the main program, but they still don't seem to think of it as anything but the single action item 'write and test a program'.

A super bonus would be strategies for making (/encouraging) people to see email as a legitimate way to 'talk' (probably a bit late for this one, with two weeks to go, but I'll know next time).

got any mod_python and cheetah resources?

karen — Tue, 14 Feb 2006 18:09:48 -0800

Can anyone point me to a good documentation/samples for building an app using mod_python and cheetah? (and mySQL/DBUtils etc)? I am planning to write a webapp (internal only) that uses mod_python and cheetah to replace one that uses php and smarty. I have downloaded and installed everything but while I've used python before, I've never used mod_python or cheetah so I've been looking for some good online resources (or books) that have sample code and other useful information. I've looked around a lot but can't seem to find anything really useful. I would appreciate any help/pointers to good resources. TIA!

Extracting XML schema documentation into lovely documentation

dobie — Fri, 09 Dec 2005 13:40:15 -0800

Help me figure out how to extract an XML schema in a .dtd file into lovely XML documentation. I have found several possible ways of doing this, ranging from command line fiddling like xsddoc to more modern approaches like Stylus studio and yet none of them have seemed to work for me.

I'm looking for nice library style results where all of the elements and tags are cross referenced and extracted automatically. Something freeware would be most desirable.

Any ideas?

how to make online docs efficiently?

anadem — Wed, 02 Nov 2005 16:40:09 -0800

How best to manage software product documentation? Our product docs are written in Microsoft Word and printed or shipped as PDF files. The online help is made by converting the Word files (in Robohelp) and adding lots of hyperlinks. This process has snags. The problem is over how to manage document changes. At present the Word files are the base which is edited for product updates.

Using Robohelp it's trivially easy to convert the .doc files to online form, but that loses all the work which went into the hypertext links. On the other hand, adding the changes manually to the hypertext is also a lot of work, and error-prone.

Surely there's a better way?

How do I get my work onto slide film without shooting on slide film?

tarintowers — Tue, 18 Oct 2005 15:57:40 -0800

Methods of Documentation: Getty My Work Onto Slide Film Next weekend I am participating in an art show, my first in which work will be for sale, and because for one thing, I hung a piece in the silent auction, I have reason to believe I will sell at least one thing. (I have sold work before on commission, but this is still pretty exciting.) I would like to have, in the future, in my portfolio, slides of any sold work. I do not have a tremendous budget but I'd rather spend a bit of cash than not have documentation of early sold work. What method should I use to get my paintings and soforth onto slides? (See extended explanation). Thanks much. I've got until the weekend to figure this out. /tarin Should I:

1. Hire a slide photographer to shoot the work hanging in this show?

2. Shoot the work myself on slide film with my 35mm SLR, even though I've never shot on slide film before?

3. Shoot the work myself on digital, and THIS IS WHAT I REALLY WANT TO KNOW: Take it to the photo shop, where they can magically process a digital CD into a slide roll? Is #3 here possible?

4. Because time is a constraint and so is money, shoot the work myself on digital, project it onto the wall, and shoot that with slide film later when I have more leisure to shoot and get it right?

What would you do?

Suggestions on documenting employee performance?

cyniczny — Mon, 08 Aug 2005 15:34:20 -0800

Suggestions for organizing and documenting employee performance that can be used in annual reviews? I'm responsible for writing annual reviews that fall on the employee's anniversary date. There are from 10-12 employees, all with various titles and job duties. The reviews are quite long, and don't involve 360 feedback, so I have to gather, document and maintain a great deal of information, including as many examples as possible to support the review information. I've tried notebooks, notecards, hand-written docs at the end of the day, weekly updates, etc. I never seem to have thorough enough records and really need to hear suggestions for how other people keep track of this stuff that won't take a ton of time. I'm a hands-on manager, so my desk time is very limited and my computer is in public view so keeping documents open all day to add info to doesn't seem to work well. Any suggestions are welcome. I'm willing to try most anything! (P.S. - using a PDA for this is not an option).

Tools for writing application documentation

turbodog — Tue, 14 Jun 2005 11:53:45 -0800

For the purpose of documentating an application, I'm looking for a WYSIWYG editor that can yield both in HTML and PDF formats, but meets a few other criteria. [More Inside] Criteria:
- Need WYSIWYG: don't want to muck with HTML across a large document
- Need HTML: organized and hyperlinked from a table of contents at the top, so it can be read "top down" or as in-program documentation by linking to the appropriate page.
- Need PDF: shouldn't be a big issue since I can probably render PDF from whatever HTML I end up with.
- Need automatic TOC generation/upkeep that links to the referenced item
- Nice to have: automatically include a link back to the TOC at the end of each section. If I had to do this by hand it wouldn't be the end of the world.

What I already considered:
- Word: WYSIWYG, does the TOC the way I'd like, but really afraid of the HTML it would generate
- Open Office: WYSIWYG, does TOCs but doesn't link to the referenced location, HTML hopefully sucks less than Word's
- Generic WYSIWYG HTML tools: don't automatically do a TOC

Any ideas on other tools I could check out? Free/open source solutions a big plus.

Collecting/numbering tax documents of different filetypes and exporting to PDF or Word.

airguitar — Tue, 22 Feb 2005 14:35:12 -0800

Does anyone know of a program for Windows 2000/XP that will bring several different types of document files and image files together into one interface? This application should be able to reorder and renumber the pages accordingly. Also the tool must be able to export the end product into a universal format such as PDF or Word. My company will use this tool to build our tax returns. As I understand it, our returns consist of a collection of output from several sources: Hard copies scanned to .TIF images, PDFs, XLS files, DOC files, etc. Last year we started using Xerox PaperPort to scan in all the hard copies, reorder and renumber pages, but the renumbering of pages, in particular, was incredibly laborious. Pages are added and removed from the return on a constant basis almost to the zero hour, so the renumbering of pages needs to be a very accessible and simple-to-use feature.

Any recommendations on an application that will fulfill this need or suggestions on how to better the creation of the return are appreciated.

p.s. this question is from my friend Sublivious.

Do US citizens need a passport to visit Canada?

jare2003 — Tue, 09 Nov 2004 13:36:03 -0800

If I am a US Citizen, and want to go to Canada for a few days, do i need a passport? I had one, but it was stolen, I'm a poor student right now, so i dont have the cash (or time to wait) for a new one to come. Is a driver's license or birth certificate considered official enough documentation?