Author Topic: The best way of documenting software  (Read 4238 times)

Offline doppelgangland

  • Acquaintance
  • *
  • Posts: 31
    • View Profile
The best way of documenting software
« on: April 04, 2007, 10:51:01 am »
I've been thinking hard about the ways software is normally documented and I'd appreciate your feedback about my ideas.

I think it can be said aloud how hard it is for newbies to learn how a piece of software works if they first have to sort out how best to deal with duplicated documents, FAQs, tutorials and release notes on top of that. (Crat, please don't take this as negative criticism --I really think your mudlib is the best documented out there--. I know you're more a coder than a writer. I only mean to test an idea here.)

Now, what I mean is this. I think it might be a good idea to unify all the documentation of a project --and I really mean any project-- in a single unified rtf document and publish it as a pdf. This document should contain every single piece of information about the project in separate sections. Imagine all release notes, instructions, examples, FAQs, tutorials and walkthroughs in a single file that stays up to date with info from forums, devs, etc. I mean, wikis and web sites and forums are OK, but I think that fragmenting and repeating information like this is really inefficient.

(NOTE: The good thing about pdf is that you can include pics and the reader is free, so that you don't need to buy expensive software to read the document, plus you can take it anywhere, print it, etc. --I got the idea from the linux documents at http://www.tldp.org/.)

I'd like to know what you think. Thanks for your time.
« Last Edit: April 04, 2007, 10:56:16 am by morlock59 »
We shall fight on the beaches, we shall fight on the landing grounds, we shall fight in the fields and in the streets, we shall fight in the hills; we shall never surrender.

Offline cratylus

  • Your favorite and best
  • Administrator
  • ***
  • Posts: 1024
  • Cratylus@Dead Souls <ds> np
    • View Profile
    • About Cratylus
Re: The best way of documenting software
« Reply #1 on: April 06, 2007, 09:26:38 pm »
Heckuva good question.

I think I've done a lot of good documentation, but I also think I've done a
lot of not-good organization of that documentation. I'd be interested in
hearing suggestions...and if someone wants to take part in bettering
DS by helping organize the docs, I'd be thoroughly tickled pink.

-Crat

Offline saquivor

  • BFF
  • ***
  • Posts: 111
    • View Profile
Re: The best way of documenting software
« Reply #2 on: April 08, 2007, 01:04:59 pm »
Saquivor the bot points to http://lpmuds.net/forum/index.php?topic=213.msg357#msg357

and then winks out of existence again.

Offline doppelgangland

  • Acquaintance
  • *
  • Posts: 31
    • View Profile
Nice start
« Reply #3 on: April 11, 2007, 03:38:28 am »
It's a nice start, saquivor, but it still contains duplicated material, no faqs, no release notes, etc. I was thinking more along the lines of a reestructuration of existing material, centralization and deletion of repeated things.

But thanx, anyway.
We shall fight on the beaches, we shall fight on the landing grounds, we shall fight in the fields and in the streets, we shall fight in the hills; we shall never surrender.

Offline saquivor

  • BFF
  • ***
  • Posts: 111
    • View Profile
Re: Nice start
« Reply #4 on: April 11, 2007, 10:13:16 am »
It's a nice start, saquivor, but it still contains duplicated material, no faqs, no release notes, etc. I was thinking more along the lines of a reestructuration of existing material, centralization and deletion of repeated things.

But thanx, anyway.

Adding  faqs and release notes to the script I wrote would be so simple I am not even going to explain it.

Pretty pictures and a proper index structure could also be easily added. The script was designed so it would always take the latest version of docs from a release and merge them together.

Please feel free to ignore my remarks, as I am only forum bot :P

Offline cratylus

  • Your favorite and best
  • Administrator
  • ***
  • Posts: 1024
  • Cratylus@Dead Souls <ds> np
    • View Profile
    • About Cratylus
Re: The best way of documenting software
« Reply #5 on: April 11, 2007, 10:33:29 am »
For a bot, Saq has contributed dramatically to Dead Souls. He made the current port to Windows
possible by contributing working sockets code, and his database expertise made it possible to
convert this forum from the old Beehive style (for an example, see here: http://www.tehforum.co.uk/forum/ )
to this pleasing Simplemachines style.
(It was a right pain, believe me, and I couldn't have pulled it off without an actual expert).

I think I've been hoping he takes on DS doc cleanup too...but I don't know what else to name
after him on the lib. He's already got a street!

I think Morlock has identified a real weakness in the lib. I've seen new DS adopters show up and
complain about there being "no docs", or asking stuff like "how do I make my friend an admin",
which of course makes me begin weeping uncontrollably, having written literally hundreds of FAQ
items answering just such things.

If anyone wants to take up the job of centralizing and managing this material and
being DS docsmaster, I'd gratefully discuss with them their vision and plan, and hopefully
things could improve. I really have no idea how to make docs more accessible and useful,
and am humble enough to admit I can use the help in organizing them.

Also, I'm lazy, and even if I knew, I'd likely not do it myself ;)

So, any takers should IM or email me or talk to me on intermud, and we'll go over
your ideas n stuff.

-Crat

Offline doppelgangland

  • Acquaintance
  • *
  • Posts: 31
    • View Profile
My vision is this (I hope it is clear)
« Reply #6 on: April 11, 2007, 11:28:54 am »
Project OneDoc (title)
This is the web site for (put title here) Project OneDoc. This project intends to (here comes the purpose) give a solution to those who want to have all updated content of a project in one single place.

How many times have you wished you could browse all official documentation about something without having to search around in separate forums, FAQs, Tutorials and wikis for the bit of information you need? Well, no more. This is the solution to all that.

Plus, you can download the complete documentation and view it offline at your convenience.

Table of contents (TOC)
Original documents
FAQs
Tutorials
Howtos
Walkthroughs
Notes (release notes here; older notes will be merged with the text in time)
Related documents
Links

--------------------------------------------------------------------------------
Download complete documentation now (last modification: 4/12/2007)!
(NOTE: Clicking on the above link will get you a zipped copy of the latest version of all the documentation subfolder in this website. It contains all publicly available documentation on this project up to the date indicated above.)
« Last Edit: April 12, 2007, 05:56:44 am by morlock59 »
We shall fight on the beaches, we shall fight on the landing grounds, we shall fight in the fields and in the streets, we shall fight in the hills; we shall never surrender.

Offline saquivor

  • BFF
  • ***
  • Posts: 111
    • View Profile
Re: The best way of documenting software
« Reply #7 on: April 17, 2007, 04:44:24 am »
I have produced some updated documentation files, so that you can use them to help with your project.

pdf version
txt version

Personally I like windows style chm documentation. But not sure if they work on *nix.

If I could produce these files in a more helpful way then please let me know.

Saquivor

Offline doppelgangland

  • Acquaintance
  • *
  • Posts: 31
    • View Profile
Re: The best way of documenting software
« Reply #8 on: April 17, 2007, 06:32:37 am »
What you have done is totally amazing. Thank you very much!

I've made a front-end web page interface to nearly all the documents in the mudlib, which suggests a reading order at the same time, so that it's easier for noobs to get used to it without getting overwhelmed.

I've submitted it to Crat for revision to see if he likes it or what. The way I see it, your option totally rocks for having it all in one place, but it's not sufficiently user-friendly for newbies. I'll keep thinking about finding a way to integrate it all.

Thanx for your time.
We shall fight on the beaches, we shall fight on the landing grounds, we shall fight in the fields and in the streets, we shall fight in the hills; we shall never surrender.

Offline skout23

  • Acquaintance
  • *
  • Posts: 17
    • View Profile
Re: The best way of documenting software
« Reply #9 on: May 03, 2007, 01:22:34 pm »
I actually like the chm format as well, and yes there are viewers available for *nix variants.  Heck Ubuntu supports it out of the box.