Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

Re: creating documentation

by astaines (Curate)
on Dec 28, 2005 at 00:20 UTC ( #519464=note: print w/replies, xml ) Need Help??


in reply to creating documentation

Important preliminary question - Who are your intended audience?

  • You, and maybe the other core developers e.g. Maple
  • Other programmers using your elegant library or your lovely module e.g. libkdepim or DBI
  • Other people installing your cooooool system e.g. Apache, Slashcode
  • Normal techy people using the software e.g. R
  • Normal non-techy people e.g. OpenOffice

These groups need very different documentation. To produce good documentation you need to know your users. Perhaps the only common thing is that they all need and will benefit from copious annotated examples!

-- Anthony Staines

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://519464]
help
Chatterbox?
[choroba]: The problem was bigger, as the test tried to call a method that didn't exist anymore
[marinersk]: :: ducking ::
[choroba]: because, someone renamed the method, but didn't notice it was used in the test, as the test was skipped
[marinersk]: Well, if the method doesn't exist, it would be hard to pass the test.
[choroba]: later, someone removed the new method, as all its usage places were safe, but didn't notice the test still used the old name
[choroba]: fortunately, it wasn't that hard to replace the method and fix a few remaining failures due to the changes we did to the codebase over the years
[marinersk]: choroba Sounds like a process improvement opportunity; tests may not all need to be run, but they should all be compiled with perl -c before check-in/promotion happens.
[choroba]: so, now I have the test, so I can start making changes in the code. Back to the original ticket, yay!
[marinersk]: I definitely love it when my $current_taask=& taskPop(); if ($current_task eq $original_task) { } is true.
[marinersk]: s/taask/task/g;

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (14)
As of 2017-05-25 15:14 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?