Click here to Skip to main content
Rate this: bad
good
Please Sign up or sign in to vote.
Dear Friends,
 
I want to make a technical documentation of an existing web site for developers so that new developers can continue to work with it. In existing codes, little (or not at all) in-code comments or doc-strings are available (bad practice, I know). Yeah, I have seen some posts related to these. But those were not that detailed. Here are all my questions:
 
What to include?
How to organize? I mean, can you suggest some hierarchy so that new developers can easily get onto the track?
What are the best practices?
Can you show some samples?
How can it be made easy?
Some ppl suggests wiki tool but I know nothing about it, will it be useful?
Can you suggest any tool with some quick starting tutorial?
I have never made one. So I appreciate any kind of answer.
Thanks in advance.
Posted 17-Aug-12 19:02pm
Comments
Sergey Alexandrovich Kryukov at 18-Aug-12 0:29am
   
Not a bad question; I even voted 5 which really rarely happens, but... too big for this forum.
--SA
Arunprasath Natarajan at 18-Aug-12 3:48am
   
Tan q, will take care in future.

1 solution

Rate this: bad
good
Please Sign up or sign in to vote.

Solution 1

This question is too big to answer in detail, especially for this Quick Questions & Answers forum.
 
I would like to share just a few thoughts.
 
First and foremost, documentation writing should be a part of the same process as software development. And the first thing you need to use is the Revision Control System, and certainly the same as the one used for the development, and documentation for the product and its source code should be in the same project of the Revision Control.
 
For the problem of selection of particular Revisions Control System, please see this discussion:
Revision control systems, which to choose from?[^].
 
Please see my past answers:
Needs some words of wisedom to set up and/or use a server[^],
Make an unclickable form[^],
How can i structured to arrange source code when i create a new solution[^].
 
As to the Wiki, I think this is a very good idea.
 
I did not try many, tried to find something extremely light weight, and all I tried did not work properly. So, I have quite positive experience only with one product, Wiki which was integrated with Trac. Please see:
http://en.wikipedia.org/wiki/Trac[^],
http://trac.edgewall.org/[^].
 
And, as Trac itself had very good integration with Subversion, I had a well integrated bundle which was easy to maintain. I did it all on Ubuntu server I set up specifically to have a development server (for international distributed team). Issue tracking provided by Trac is also a kind of documentation of special sort, but it was also very convenient way to write Wiki and make it bound with issue tracking and parts of projects, via cross references.
 
See also:
http://en.wikipedia.org/wiki/Subversion_%28software%29[^],
http://subversion.apache.org/[^],
http://en.wikipedia.org/wiki/Revision_control[^],
http://en.wikipedia.org/wiki/Issue_tracking_system[^].
 
And one more thing which might look very strange to many, and many will criticize me for that, but all my experience tells me about it. There is one important and robust Visual Studio feature: XML comments which documents the code and shown in Intellisense and while browsing of the referenced .NET assemblies. Here is my advice: don't overdo it. These comments highly reduce readability of the source code, especially during development. Delay such documentation to the moment when the assembly is mostly used and almost not developed anymore. Comment this way only visible (public) types and members. For all other cases, use lapidary usual comments; make code more self-documenting.
 
It's possible to keep talking about documenting forever, but let's again remember this is the Quick Questions & Answers forum. I think, for now it's enough.
 
—SA
  Permalink  
v4
Comments
@amitgajjar at 18-Aug-12 0:31am
   
thanks SA for sharing your thoughts ... i want to vote 10+ but it's not there... so 5+ for you :)
Sergey Alexandrovich Kryukov at 18-Aug-12 0:34am
   
Thank you, Amit.
--SA
@amitgajjar at 18-Aug-12 0:34am
   
i am looking forward for an article on this topic. Can you share your experience in form of an article ?
Sergey Alexandrovich Kryukov at 18-Aug-12 0:40am
   
Thank you for this question, but no. I mostly do highly innovative projects, where documentation was minor compared to other works, so my experience is limited, despite of the fact that I usually write more than anyone in the team (and probably give the most wordy answers here at CodeProject :-). Besides, I have several projects for the new articles and not enough time for publishing them, so my article projects wait in line and I don't want to add more at this time.
 
Thank you,
--SA
@amitgajjar at 18-Aug-12 0:43am
   
No problem. i will wait for your other articles. Thanks.
Sergey Alexandrovich Kryukov at 18-Aug-12 0:44am
   
My pleasure. I did not expect to meet such a dedicated reader. For the record, at the moment of writing, CodeProject already has 5 of my articles.
--SA
@amitgajjar at 18-Aug-12 0:49am
   
Pleasure is all mine. I used to follow your answers. But for the articles, I didn't know you are such a valuable contributor. I just checked your articles.
Sergey Alexandrovich Kryukov at 18-Aug-12 0:55am
   
Great. I'm always grateful for feedback, including qualified criticism.
--SA
Arunprasath Natarajan at 18-Aug-12 3:53am
   
Well Said SA, Hope it will help others too. Tan q for the same.
Sergey Alexandrovich Kryukov at 18-Aug-12 12:02pm
   
You are welcome.
Good luck, call again.
--SA
Mika Wendelius at 19-Aug-12 7:55am
   
Nice answer
Sergey Alexandrovich Kryukov at 19-Aug-12 20:09pm
   
Thank you, Mika.
--SA

This content, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

  Print Answers RSS
0 OriginalGriff 7,903
1 Sergey Alexandrovich Kryukov 7,192
2 DamithSL 5,604
3 Manas Bhardwaj 4,986
4 Maciej Los 4,820


Advertise | Privacy | Mobile
Web03 | 2.8.1411023.1 | Last Updated 18 Aug 2012
Copyright © CodeProject, 1999-2014
All Rights Reserved. Terms of Service
Layout: fixed | fluid

CodeProject, 503-250 Ferrand Drive Toronto Ontario, M3C 3G8 Canada +1 416-849-8900 x 100