Web Analytics Made Easy -
StatCounter Software Documentation - Technical Writing - CodingForum


No announcement yet.

Software Documentation - Technical Writing

  • Filter
  • Time
  • Show
Clear All
new posts

  • Software Documentation - Technical Writing

    So i started the documentation (just to give me something different to do for a while) of my closed source project. I looked at several options including wiki, mediawiki, gitHub pages, and some other specific software designed for software documentation. I also looked at how other projects did their documentation.

    In the end i decided to go with a sub folder on the domain example /docs. Seems now days thats the popular and more reasonable way to do it. Also there is quite a bit of learning curve with software and even mediawiki.

    So now that i have a basic format of the design.. im wondering if i should keep the documentation private for users only either via login or just a user key they get with the sale. At least now im thinking maybe with it being closed source its not a good idea to have the docs viewable by the public, but i have not decided for sure on that one. There is good and bad either way. I need to find some closed source software examples and see if they show their docs to the public.

    But anyway here is my basic format. The white is just where i removed text, its all the same background color with white text. The green text is the visited color, otherwise its off white.

    Click image for larger version  Name:	docdesignsample.jpg Views:	0 Size:	46.7 KB ID:	2424663
    Last edited by durangod; Jun 29, 2020, 07:56 AM.
    If a php file only has php code within it you do not need to use the closing php tag
    A good way to remember objects from arrays is you shoot objects with arrows Example: $name->id; then Arrays are $name['id'];
    durangod is short for durango dave

  • #2
    I've been writing my documentation in raw HTML for some time, as it's very much well suited to the task. Particularly when it comes to cross-referencing sections. Hash links and anchors just make getting around a breeze, and if you leverage CSS' :target, you can make it all one giant page that's easily copied or printed, whilst faking the behavior of normal website navigation.

    I mean sure, I might end up with 240k of HTML on something like my x86 instruction reference, but it's actually faster overall. With CSS doing most of the heavy lifting the result is a page that -- even with the massive HTML -- is smaller than most AJAX driven navigation whilst providing most of the same benefits.

    Server-side I maintain each sub-function/part separately, and glue them together into a single static file whenever I make an update. That way I can just focus on starting each section with an H2, putting together common elements with PHP functions, even having forward and back built off the directory structure/files.
    I'll kill you and your dreams tonight, begin new life.
    Bleed your death upon me, let your bloodline feed my youth.


    • #3
      DS I like that idea, and i have actually done a very similar setup on small to mid size projects in the past. That is when my mind was much sharper and able to juggle all the pieces at one time on the page. Now days its different i have to focus on one piece at a time, so that means more segregated files and folders. Admin docs in one folder, and user docs in another. Each one shares a common included header, menu, and footer file but the content is file specific. This way not only can i focus on the documentation in specific in the file, but my mind seems to handle the file and folder structure much easier not having all the code in one file, or those files in one directory.

      I also find that naming conventions help a great deal as well (just like the project files) so rather than for example configadmindoc.php i can make them all more common as admin_config_doc.php and admin_dispute_doc.php. I even considered using a different file extension but im not sure if i could use something like .doc for a php file and that ext is taken anyway by another software. Yes i make them all php files because it easier now to set them up to handle php than it is to make them just html and then have to convert them later to php if you need to use php.

      But regardless its a long long long and mindnumbing process from start to finish. I suppose the best part about it is that there are no rules, one can create at will without being bound by technical writing rules as i dont think there are any other than spelling, no run on sentences, and use paragraphs alot, but that goes for any writing project.
      Last edited by durangod; Jun 29, 2020, 05:21 PM.
      If a php file only has php code within it you do not need to use the closing php tag
      A good way to remember objects from arrays is you shoot objects with arrows Example: $name->id; then Arrays are $name['id'];
      durangod is short for durango dave