The Joel on Software Discussion Group (CLOSED)

A place to discuss Joel on Software. Now closed.

This community works best when people use their real names. Please register for a free account.

Other Groups:
Joel on Software
Business of Software
Design of Software (CLOSED)
.NET Questions (CLOSED)
TechInterview.org
CityDesk
FogBugz
Fog Creek Copilot


The Old Forum


Your hosts:
Albert D. Kallal
Li-Fan Chen
Stephen Jones

Help!  I hate creating documentation!

I have been working on SD projects for several years, and I'm finding that documentation is my least favorite part of the job.  Reading the JOS essays about how to create fun documentation didn't inspire me.  Documentation is a critical aspect to any software engineering effort, but I just can't get motivated.  Is there any hope?  Should I give up on this profession now?  Perhaps it is because I feel overwhelmed at the task because the documentation I have envisioned is quite verbose and detailed.  Is it "cheap" to use screenshots to document complex configurations, or do I have to use well formatted MS Word tables?  (Ickkk!)

I realize that in posting this question and being honest about my dislike for documentation that I will never ever have a chance at working for Fog Creek Software *cuckle* but I am willing to consider ways to this daunting task easier based on any suggestions you may have.  I feel like I have more than writers block.  (More like a disease)  Any help you can offer will be greatly appreciated.
SteveT Send private email
Tuesday, September 06, 2005
 
 
You're probably not alone in your abhorrence for documentation.  I too naturally believe that I dislike documentation, but that isn't entirely true.


For instance, while coding in C, I usually have a 75%/25% comment/documentation-to-source-line ratio.  My current project is 100K C lines, but 70K+ lines are function or block headers with implementation notes.  Thus, internal source documentation doesn't bother me.  In fact, I rely on this thought process & development to better steer me in the direction of correctly implementing the requirements.


Also, while designing, developing, & testing, I hand write notes & diagrams to ensure correct design & implementation.  Some of these notes/diagrams are temporary only to get a minor detail implemented.  Others illustrate the design & implementation & perhaps even verification.  Some of these could even be added to the project's manual or user manual.  Thus, notes or diagrams don't bother me.


But writing the final user's manual can be a painful task.  And I've had to ask myself why that is.

For starters, documentation varies from company-to-company, project-to-project.  How should THIS project be documented, what should be said, how, where?  Lastly, how should it be formatted or appear regarding graphics, logos, etc.?

And regarding formatting, almost all our documentation is developed in Microsoft Word.  Word is one of the few programs that can get me cussing & cursing in no time flat.  Auto-formatting (whether it's disabled or not) & hidden formatting are two of the worst features ever developed.  Once Word starts "taking over" your documentation, you're pretty much screwed.  Saving often & restoring to previous saved versions helps, but one shouldn't have to go to such lengths to use a word processor.


Perhaps you share some of my likes/dislikes regarding documentation, but if you have to document, take as many of the pains away as possible.

If you have to "cheat" by pasting graphics of the application in the document, so be it.  If it's easier to create graphics in another program before embedding in your document, go for it.

Do whatever it takes to make documenting easier, because the writing should be the most demanding aspect & for some of us, that's already daunting enough.
Ian Johns
Tuesday, September 06, 2005
 
 
I think we also know what good documentation is, and want to produce it.  Unfortunately, it's just damn hard to do that since you already know how it's supposed to work.

It's like UI testing -- the best way to figure out if something is adequate is to give it to a relative neophyte and start asking them questions that they should be able to answer.  You'll find your inadequacies fast then.  That might help motivate you, watching someone succeed/fail based on your help is generally good motivation to give good help.

And it's like regular testing:  Probably best left to someone else.  If they start learning to use it at the same time they write the documentation, their mindset will be that of the new user:  How to fastest get going.  They'll have a lot of questions and annoy you a bunch, but they'll probably have some interesting insights.
Ryan Phelps Send private email
Tuesday, September 06, 2005
 
 
One way to make it a little less painful is to use something like dokuwiki when doing your functional specification. DokuWiki allows lots of pretty formatting, etc. so if you do some fairly thorough functional specs, the final documentation should be an update and edit of the spec.

I realize this is still painful, but if you have a good spec, it can often form a good basis for the end user documentation with examples built right in.
Bart Park
Tuesday, September 06, 2005
 
 
Suck it up.

There are lots of techniques to make doc writing less painful which have been mentioned above, but nothing you do can make it any less necessary. Some people hate it so much, they have invented entire programming methodologies around writing less documentation!

This might be good for you. If you can use in-code documentation techniques (like JavaDoc) or code-as-spec (Agile methods). But don't think you can get away with not writing docs, or writing less detailed docs! You'll not only ruin your own projects by doing so, you'll help promulgate the stereotype that we bit-flingers aren't really capable of planning.
Robby Slaughter Send private email
Tuesday, September 06, 2005
 
 
There's a halfway house. Get all the information down, including screenshots, then pass it onto a freelance technical author like myself.

We can pretty easily turn it into precise English (with the ambiguities resolved), set out the information so that it's accessible, spruce up the look, and of course bolt on the usual table of contents, index and so on.

That's our skillset, what we do for a living. It's no more cost-effective for a coder to techwrite than it would be for a techwriter to code.
Hackwriter
Wednesday, September 07, 2005
 
 
Had this idea while reading this thread, never tried it myself. How about: Take the thing you want to document, take someone who doesn't know too much about this thing. Explain the thing to him, answer his questions, until he understands the system. Record the whole conversation (beware, it may be illegal to do this without the other's knowledge and consent), and write down the recordings afterwards, including questions/answers. Now you should have a nice conversation line you can write the documentation along, with halfway ordered thoughts, and it should be quite easier to start from there than from nothing.
Secure
Wednesday, September 07, 2005
 
 
that's not bad, Secure.

I like perl's perldoc thing, and intend to use it more.

There are actually two sides of documentation:

- docs for the guy who will have to maintain your code. COde should be self documenting as far as possible, with the exception of the high level "how it all works" doc, a bit like the spec Joel posted a while back. This should be partly done in advance and updated with the project.

- the other part is docs for the users of your code, who don't have to look inside. That means either documenting an API, a UI, or both. Again a lot of this should exist in some form before you start.

So start off with decent proposals for user guides/system desc's, and keep them up to date.

So why does it never seem to work that way?
prefer to be anon
Wednesday, September 07, 2005
 
 
Nice idea.Rather time-intensive, though! Really, you're just reinventing the wheel here.

Wouldn't it be cheaper to go through same exercise, but to explain the system to a techwriter, who then went off and did the work, leaving you to do uber-geek stuff?

For example, on the UK jobserve, I see ads for java programmers offering £500-£600 a day. Techwriter rates are more like £200-£250 a day.

So, say it's a 20-page manual and that I'm twice as fast as java guru.

Suppose java guru does it:
1 day to assemble information form: £500
2 days to write the manual: £1000
Total cost: £1500 for something which still doesn't look very professional (and will cost another £200 to fix at some later date)

Suppose I do it:
Half a day to gather information: £100 for my time, plus £250 for java guru.
1 day to write: £200
Total cost: £550 for a proper professional manual

Oh, and if a good spec exists in the first place, the cost would be more like £200.

So, why are you even discussing how to write documentation? Go find yourselves a local techwriter!
Hackwriter
Wednesday, September 07, 2005
 
 
The secret of user documentation is the knowledge that it is a REFERENCE manual, not a proper USER GUIDE.

If it were a user guide, you wouldn't be writing it, some famous author like Michael Crichton (or maybe TOM CLANCY) would be.  So we know (!) that this isn't the case.


Now that we're sure you're going to be writing a reference for your program, step one is to stop trying so hard--really, no one will care.  Really, you can relax now.  Step two is to make an outline of everything you're going to cover in the manual.  Feel free in this step to remove any section headers that may be problematic in implementation.  Be sure to tiptoe around anything that might require a diagram or lots of wordy expositions--just remove them from the outline.  Trust me, no one will notice!  Step three is to fill out everything between the (remaining) points of the outline and use Word's auto-"Table Of Contents" feature and auto-"Index" feature to do the rest for you.  Step four is to lay back, task 100% complete!

Citing sources: http://secretgeek.net/TechSuppDocs.asp
pds Send private email
Wednesday, September 07, 2005
 
 
> I have been working on SD projects for several years, and I'm finding that documentation is my least favorite part of the job.

Having just been through two largish systems who believed the source code is the documentation, I must say I dislike your type intensely :-)

Be a professional. Your code isn't done until you write documentation. Write the documentation as you code, then you don't have to do it later.
son of parnas
Wednesday, September 07, 2005
 
 
Spend some time maintaining somebody elses code.

I've been doing it for half a decade.  In that time I have learnt to really appreciate the value of good quality documentation.
Ged Byrne Send private email
Thursday, September 08, 2005
 
 
Two completely different forms of documentation are being mixed up in this thread: user documentation and programmer documentation.

For programmer documentation think of: lines of code ratios, JavaDoc, code headers, contracts, maintenance programmers.

For user documentation think of: recording an actual user, hiring a specialised writer.

This distinction is so important that the question becomes almost meaningless when this choice is not made explicit.
Karel Thönissen Send private email
Thursday, September 08, 2005
 
 
Two things that help, in my experience:

- learn to touch-type
- focus on content, not format and layout.  Think who you're writing the document for, and what they _need_ to know.  Focus on that.  Let the topics that they need to know  dictate the structure of the document, not the other way around.

I think that may people get "stuck" on documents because they belive the reader expects some standard format, with some standard set of headings.  I think you get better documents, with less pain, if you start by brainstorming "what do I know, which would be helpful to my readers", and then write about that in whatever structure fits what you have to say.
John Rusk Send private email
Thursday, September 08, 2005
 
 
...in other news:
"A recent study has determined that 99% of developers have a strong aversion to preparing documentation. Police are currently searching for the remaining 1% as they are believed to be mentally unstable and highly dangerous. It is hoped that with sufficent therapy and sedation they may however be suited for a role in management."
just kidding
Friday, September 09, 2005
 
 
Reap what you write

 ... nobody bothers to read technical
 documentation anyway. Unless of course
 they are stuck, its four o`clock in the
 morning and the phone lines are down
 ...

If you haven`t browsed the ITConversation [3] site you might have missed Joel`s talk with Doug Kaye called Technometria. [4] Its worth the listen because it highlights both the need and more importantly some insights into how we can all improve our writing. A good follow-up could also be the introduction article, `Introduction to the Best Software writing` [5] Joel refers in the talk.

The main crux of Joels argument is most technical documentation is poorly written. Nobody bothers to read technical documentation. Unless of course they are stuck its four o`clock in the morning and the phone lines are down. The flip side is when they do need help, they want to be able to understand and apply. This is where your document fits in.

So how do you avoid staring into a blank screen, waiting for the words to flow?



Know your reader?
When you write your documentation, first capture the readers attention allowing them to absorb the information they require. So like every hunter you must know you reader well. Recognise that different users have different requirements.
    * Know your user
    * Identify their needs.
    * Modify the documentation to their needs.


Technical:
If your audience is technical with a background in software development, the technical documentation may suffice. For example, the documentation required for a developer to build a user interface differs greatly from the documentation required to fix a bug or re-factor code.

    * HCI, GUI -> functional design -> how code works from user viewpoint
    * Architecture -> design documents -> technical view of how code works
    * Re factoring -> class structure -> big picture to improve product
    * Debug -> function signatures -> specific focus to fix a problem
    * Code -> example code, unit tests -> specific example how to use code


Ordinary:
If you audience is non-technical it is more than likely more general information is needed. For instance,
    * How do you use?
    * Understand context of how/where the technology fits in.
    * How to best apply?

User requirements drive the type of documentation required. You must also understand the choice of document format should be specifically tailored to the scope of the users problem.

    * Starting from scratch -> General -> Book, introduction articles on specific topics
    * How to do a particular task -> Detailed -> HOWTO, article
    * Solve specific problem -> Comprehensive -> FAQ or forum
    * Why doesn`t this work -> Specific -> bug tracking database
    * Latest updated feature -> Timely -> Forum, article

There is a huge difference between finding the answer to a specific problem compared to finding out what operating system is required. Take for example the above list. Each solves a problem,  has a scope and  potential documentation format.


What type of software do you produce?
Not all software is created equal. Nor should it be. Is the software ...
    * For yourself?
    * Is it for internal use?
    * Developers?
    * In-house application, deployed for company wide use?
    * Embedded?
    * Or the shrink wrapped market?

What type of software you produce will dictate documentation focus. For example,
    * Personal -> comments, source code
    * Open source -> source, comments, man, README, INSTALL, Faq
    * Developers -> source, design docs, generated docs from source
    * Internal business app -> Faq, wiki, forum, manual
    * Shrink-wrap -> Forum, wiki, faq, email, articles, book.

So modify the type of documentation to fit your software.


How can I better utilise technology?
Always look to see if you can use technology to leverage your documentation. Technology can be used as an amplifier to improve the
    * Quality
    * Quantity
    * Diversity

of existing and new information. Technology can also be applied to the following:
    * Generation -> How can you generate docs from source code?
    * Timeliness -> How can you use technology to generate latest changes?
    * Format -> How can you export your documentation to many different formats?
    * Accuracy -> How can you use your expert user base to improve information accuracy?
    * Community -> How can you enlist your user base to generate your documentation for you?


When do I need external help?
 Ernest Rutherford is oft quoted as
 saying,. `In science there is only
 physics; all the rest is stamp
 collecting.` [6] The same goes for
 writing. Good writing is a pleasure to
 read, whatever the topic. Anything else
 else is ignored. Whatever the topic.

Sometimes you may have to face facts and call in the professionals. Technical writers. But this is an extreme case. Most software documentation is for internal use and not a shrink-wrapped product. So take Joel`s advice [7] and learn to write.



Reference

[3] ITConversations, downloadable mp3 talks with tech/IT giants:
http://www.itconversations.com
[Accessed Saturday, 10 September 2005]

[4] `Joel Spolsky`, Technometria, talk on the hows and whys of better writing:
http://www.itconversations.com/shows/detail599.html
[Accessed Saturday, 10 September 2005]

[5] `Joel Spolsky`, Accompanying article for Technometria. Demise of technical writing. How can you fix it?:
http://www.joelonsoftware.com/printerFriendly/articles/BestSoftwareWriting.html
[Accessed Saturday, 10 September 2005]

[6] `Ernest Rutherford`, Wikipedia:
http://en.wikipedia.org/wiki/Ernest_Rutherford
[Accessed Saturday, 10 September 2005]

[7] `Joel Spolsky`, Painless Functional Specifications - Part 1: Why Bother?
http://www.joelonsoftware.com/printerFriendly/articles/BestSoftwareWriting.html
[Accessed Saturday, 10 September 2005]
peter renshaw Send private email
Saturday, September 10, 2005
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz