Search Results

Search found 10494 results on 420 pages for 'beyond the documentation'.

Page 3/420 | < Previous Page | 1 2 3 4 5 6 7 8 9 10 11 12  | Next Page >

• Are there good resources for leading documentation for an existing software product having none?

  - by Ben Rose

  Hello. I'm a software developer at a technology company. I have been tasked with leading the documentation effort for the product I work on, both internal to developers as well as spilling over into facilitating the business side of requirements documentation. This internal product has been around for at least 6 years. One challenge is that this software application has no form of documentation other than some small, outdated pieces here and there. There are comments in the code, but they are technical and do not convey any over-arching behavior (even on technical side). As a consequence of having little to no documentation, this product is often unnecessarily complex under the covers adding to the challenge. We are very limited on time that will be given to us to work on documentation. Another thing about me is that I've displayed some ability in writing/communication around the office, but I'm not coming from any sort of documentation or formal writing background (beyond my academic career). Please share your advise or recommend resources, book/website/forum/whatever, for helping me come up with a plan with milestones, best practices, task delegation, templates, buy-in, etc. I'm hoping for a resource targeting or giving special mention of introducing good documentation on existing projects where there previously was none. I would be very grateful for your responses. Ben

  Read the article

• printable PHP manual - 'all but the Function Reference section'

  - by JW01

  My Motivation I find it easier to learn things by reading 'offline'. I'd like to lean back and read the narrative part of a paper version of the official php manual. My Scuppered Plan My plan was to download the manual, print all but the Function Reference section and then read it. I have downloaded the "Single HTML file" version of the manual from the php.net download page. (That version did not contain any images, so I patched-in the ones from the Many HTML files version with no problem.) My plan was to open that "Single HTML file" in an HTML editor, delete the Function Reference section then print it out. Unfortunately, although I have tried three different editors, I have not been able to successfully load-up that massive html file to be able to edit it. Its about (~40MB). I started to look into the phpdoc framework with a view to rendering my own html docs from the source...but that's a steep learning curve for a newby..and is a last resort. I would use a file splitter, but they tend to split files crudely with no regard for html/xml/xhtml sematics. So the question is... Does anyone know know where you can download the php manual in a version that is a kind of half-way house between the 'Single HTML file' and the 'Many HTML files'? Ideally with the docs split into 3 parts: File 1 - stuff before the function reference File 2 - function reference File 3 - stuff after the function reference Or Can you suggest any editors/tools will enable me to split up this file myself?

  Read the article

• Is BDD actually writable by non-programmers?

  - by MattiSG

  Behavior-Driven Development with its emblematic “Given-When-Then” scenarios syntax has lately been quite hyped for its possible uses as a boundary object for software functionality assessment. I definitely agree that Gherkin, or whichever feature definition script you prefer, is a business-readable DSL, and already provides value as such. However, I disagree that it is writable by non-programmers (as does Martin Fowler). Does anyone have accounts of scenarios being written by non-programmers, then instrumented by developers? If there is indeed a consensus on the lack of writability, then would you see a problem with a tool that, instead of starting with the scenarios and instrumenting them, would generate business-readable scenarios from the actual tests?

  Read the article

• How to write comments to explain the "why" behind the callback function when the function and parameter names are insufficient for that?

  - by snowmantw

  How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on. I have always wonder why comments like this can be so ordinary in documents of libraries in dynamic languages: /** * cb: callback // where's the arguments & effects? */ func foo( cb ) Maybe the common attitude is "you can look into source code on your own after all" which pushes people into leaving minimalist comments like this. But it seems like there should be a better way to comment callback functions. I've tried to comment callbacks in Haskell way: /** * cb: Int -> Char */ func foo(cb) And to be fair, it's usually neat enough. But it gets into trouble when I need to pass some complex structure. The problem being partly due to the lack of type system: /** * cb: Int -> { err: String -> (), success: () -> Char } // too long... */ func foo(cb) Or I have tried this too: /** * cb: Int -> { err: String -> (), * success: () -> Char } // better ? */ func bar(cb) The problem is that you may put the structure in somewhere else, but you must give it a name to reference it. But then when you name a structure you're about to use immediately looks so redundant: // Somewhere else... // ResultCallback: { err: String -> (), success: () -> Char } /** * cb: Int -> ResultCallback // better ?? */ func foo(cb) And it bothers me if I follow the Java-doc like commenting style since it still seems incomplete. The comments don't tell you anything that you couldn't immediately see from looking at the function. /** * @param cb {Function} yeah, it's a function, but you told me nothing about it... * @param err {Function} where should I put this callback's argument ?? * Not to mention the err's own arguments... */ func foo(cb) These examples are JavaScript like with generic functions and parameter names, but I've encountered similar problems in other dynamic languages which allow complex callbacks.

  Read the article

• How to create programming flowchart/documentation from VB.NET source code?

  - by Greg

  Hi, what tools do you use to create programming flowchart/documentation from VB.NET source code? There are absolutely no comments/documentation at present. I am a beginner, i.e. I tried Sandcastle but it is way over my head and could not get it going, not even with GUI. Fatesoft's CodeVisual To Flowchart is OK but it is almost the same as the code and I still don't understand the code.

  Read the article

• What tools are available to generate end user documentation?

  - by Rowland Shaw

  End user documentation on how to use applications is an important part of the user experience of applications, irrespective of whether they are winforms, wpf or even asp applications. In a startup or internal development team situation, where there isn't a dedicated documentation department, it can take a lot of resources to maintain screen shots and associated user documentation, such as on-line help or even printable manuals. What tools are available to assist in creating screenshots of all the "screens" within an application (be they winforms, wpf or aspx) to help automate the capture of screen shots, and associating with the relevant documentation? In addiiton, are there any that allow automation of annotations of a particular control (so use cases like: Draw a red box around the Username control with a callout to say "This is where you'd enter your user name, in the form '[email protected]'")?

  Read the article

• Text template or tool for documentation of computer configurations

  - by mjustin

  I regularly write and update technical documentation which will be used to set up a new virtual machine, or to have a lookup for system dependencies in networks with around 20-50 (server-side) computers. At the moment I use OpenOffice Writer with text tables, and create one document per intranet domain. To improve this documentation, I would like to collect some examples to identify areas where my documents can be improved, regarding general structure and content, to make it easy to read and use not only for me but also for technical staff, helpdesk etc. Are there simple text templates (for example for OpenOffice Writer) or tools (maybe database-driven) for structured documentation of a computer configuration? Such a template / tool should provide required and optional configuration sections, like 'operating system', 'installed services', 'mapped network drives', 'scheduled tasks', 'remote servers', 'logon user account', 'firewall settings', 'hard disk size' ... It is not so much low-level hardware docs but more infrastructure / integration information in these documents (no BIOS settings, MAC addresses).

  Read the article

• What program do you use to write technical documentation?

  - by Tatu Ulmanen

  I'm writing an architecture/technical documentation for an inhouse project and I'm becoming more and more frustrated with Microsoft Word as I seem to use most of my time getting things to align correctly. Word has horrible usability issues but I didn't come here to rant, rather I'd like to know whether there exists something more suitable for the job. The point of this documentation is to provide a "big picture" of the system, and as such I'm not generating documentation from source code but rather writing it all by hand. Are there any alternatives to Microsoft Word for writing properly formatted technical documentation with less frustration?

  Read the article

• Where can I find comprehensive documentation on the various aspects of Linux?

  - by Fsando

  Whenever a problem pops up in my use of Linux (full time user for 6 years) I start by googling. The simplest (or most common) issues will usually be cleared right away. If it's not in one of those two categories the advise I find tend to be wrong, misguided, obsolete, and if you ask a question here on "ask" you risk being "duplicated" to some superficially similar question. Some issues have haunted me for years until I suddenly hit on the actual developer's documentation (or equivalent) which in a few lines explains how to solve my issue, the correct and consistent way. Whenever that happens I'm always kicking myself: why didn't I just go here to begin with? And the obvious answer is: "I had no idea this was what I was looking for". And for the issues that this hasn't yet happened I'm banging my head: "This ought to be either straight forward or someone tell me it's not doable" So my question is: Are there projects out there trying to collect or list this documentation in a searchable/browseable way. I know there are many very good "if you want this do that" tutorials on Ubuntu but I'm looking for actual documentation. That either are or could be collected in one place (at least conceptually) so that search for information could start in one place. I'm fully aware this is a broad question but if you approach it as: Does gnome have a comprehensive documentation project - where do I find it? Does Ubuntu have a comprehensive documentation project - where do i find it? For example: how exactly does the mime-type association work in Ubuntu and in xubuntu? How exactly are menus created (in Ubuntu: quicklists, xubuntu/gnome: the main menu) How exactly does the rendering process work for compiz/x? (I'm having this issue where windows randomly stops updating until somehow forced to resume (I guess). So for instance where do I look for logs that may indicate the problem. How may I change randr or other settings that may influence this issue. So my point is to organize exact documentation or preferably to find projects that do this already. Thanks! If answers to this question get me started I'm hoping to collect such a list.

  Read the article

• Posting Documentation onto a Joomla Site

  - by Chris Spicer

  I would like to create some documentation and post it onto my Joomla website. This documentation would be something along the lines of the MSDN documentation: i.e. each page would follow a basic template. Intuitively I feel I have two ways of achieving this: 1) Creating each page of documentation as a separate article, and then linking them up. 2) Creating some kind of template and filling the information from a database. The second option being preferable in the long run. Unforunately I have no idea how to achieve what I'm looking for. I hoped that there would be a component out there that woud help me, but Googling for 'Joomla Documentation' just brings up the documentation for Joomla itself. Has anyone out there put documentation on their site, and how did they achieve it?

  Read the article

• Sphinx - Python modules, classes and functions documentation

  - by user343934

  Hi everyone, I am trying to document my small project through sphinx which im recently trying to get familiar with. I read some tutorials and sphinx documentation but couldn't make it. Setup and configurations are ok! just have problems in using sphinx in a technical way. My table of content should look like this --- Overview .....Contents ----Configuration ....Contents ---- System Requirements .....Contents ---- How to use .....Contents ---- Modules ..... Index ......Display ----Help ......Content Moreover my focus is on Modules with docstrings. Details of Modules are Directory:- c:/wamp/www/project/ ----- Index.py >> Class HtmlTemplate: .... def header(): .... def body(): .... def form(): .... def header(): .... __init_main: ##inline function ----- display.py >> Class MainDisplay: .... def execute(): .... def display(): .... def tree(): .... __init_main: ##inline function My Documentation Directory:- c:/users/abc/Desktop/Documentation/doc/ --- _build --- _static --- _templates --- conf.py --- index.rst I have added Modules directory to the system environment and edited index.rst with following codes just to test Table of content. But i couldn't extract docstring directly Index.rst T-Alignment Documentation The documentation covers general overview of the application covering functionalities and requirements in details. To know how to use application its better to go through the documentation. .. _overview: Overview .. _System Requirement: System Requirement Seq-alignment tools can be used in varied systems base on whether all intermediary applications are available or not like in Windows, Mac, Linux and UNIX. But, it has been tested on the Windows working under a beta version. System Applications Server .. _Configuration:: Configuration Basic steps in configuration involves in following categories Environment variables Apache setting .. _Modules:: Modules How can i continue from here... Moreover, i am just a beginner to sphinx documentation tool I need your suggestions to brings my modules docstring to my documentation page Thanks

  Read the article

• Consulting: Organizing site/environment documentation for customers?

  - by ewwhite

  Over time, I've taken on consulting and contract engineering work for various clients. More recently, customers are asking for certain types of documentation. These are small businesses and typically do not have dedicated technical staff. Within a single company, Wiki/Confluence/Sharepoint, etc. all make sense as a central repository for documentation and environment information. I struggle with finding a consistent method to deliver the following information to discrete customers. I'm shooting for a process that's more portable, secure and elegant than a simple spreadsheet or the dreaded binder full of outdated information. Important IP addresses, DHCP scope, etc. Network diagram (if needed). Administrative usernames and passwords and management URLs. Software license keys. Support contracts and warranty information. Vendor support contacts and instructions. I know there are other consultants here. Any suggestions or tips on maintaining documentation across multiple environments in a customer-friendly format? How do you do it?

  Read the article

• What is a good/free tool to auto generate documentation for VS 2008 Express?

  - by melaos

  Hi guys, I'm new to the wonderful world of .net development, and I'm currently using c# 3.0 and I'm wondering is there any good/free/open source tool to auto generate documentation for the project that I work on based on the /// summary comments like or whatever the in thing it is for vs2008. As I recall back in .net 1.1 we used to use that with a tool call ndoc, but I can't find much about ndoc and VS 2008 express. So can anyone please recommend me some good tools or point me to the right direction? thanks. Updates: I'm currently looking into Doxygen..

  Read the article

• Bacula Documentation

  - by Caterpillar

  Hi, Any one have bacula self made documentation... Thanks In Advance Caterpillar

  Read the article

• Writing good looking documentation in pdf format on a mac [closed]

  - by Matthew

  I'd like to write some documentation that will be written in sections (1.1, 1.2, 2.1, 2.2, 2.3, etc). I'd like to use something that will generate the table of contents in the end or at least have it "linked" up so that when I make changes everything is still accurate (if I merge section 2.1 and 2.2 or something). The end result needs to be in pdf. I don't want to pay $350 for Acrobat Pro either... I've got microsoft word, but every little thing is a pain (for example, having one background of a page be a different color than another). Any ideas on how to create quality documentation in a pdf format?

  Read the article

• Enabling XML-documentation for code contracts

  - by DigiMortal

  One nice feature that code contracts offer is updating of code documentation. If you are using source code documenting features of Visual Studio then code contracts may automate some tasks you otherwise have to implement manually. In this posting I will show you some XML documentation files with documented contracts. I will also explain how this feature works. Enabling XML-documentation in project settings As a first thing let’s enable generating of code documentation under project settings. Open project properties, move to Build page and make check to checkbox called “XML documentation file”. Save project settings and rebuild project. When project is built go to bin/Debug folder and open the XML-file. Here is my XML. <?xml version="1.0"?> <doc>     <assembly>         <name>Eneta.Examples.CodeContracts.Testable</name>     </assembly>     <members>         <member name="T:Eneta.Examples.CodeContracts.Testable.Randomizer">             <summary>             Class for generating random integers in user specified range.             </summary>         </member>         <member name="M:Eneta.Examples.CodeContracts.Testable.Randomizer.#ctor(Eneta.Examples.CodeContracts.Testable.IRandomGenerator)">             <summary>             Constructor of Randomizer. Initializes Randomizer class.             </summary>             <param name="generator">Instance of random number generator.</param>         </member>         <member name="M:Eneta.Examples.CodeContracts.Testable.Randomizer.GetRandomFromRangeContracted(System.Int32,System.Int32)">             <summary>             Returns random integer in given range.             </summary>             <param name="min">Minimum value of random integer.</param>             <param name="max">Maximum value of random integer.</param>         </member>     </members> </doc> You can see nothing about code contracts here. Enabling code contracts documentation Code contracts have their own settings and conditions for documentation. Open project properties and move to Code Contracts tab. From “Contract Reference Assembly” dropdown check Build and make check to checkbox “Emit contracts into XML doc file”. And again – save project setting, build the project and move to bin/Debug folder. Now you can see that there are two files for XML-documentation: <assembly name>.XML <assembly name>.old.XML First files is documentation with contracts, second file is original documentation without contracts. Let’s see now what is inside our new XML-documentation file. <?xml version="1.0"?> <doc>   <assembly>     <name>Eneta.Examples.CodeContracts.Testable</name>   </assembly>   <members>     <member name="T:Eneta.Examples.CodeContracts.Testable.Randomizer">       <summary>             Class for generating random integers in user specified range.             </summary>     </member>     <member name="M:Eneta.Examples.CodeContracts.Testable.Randomizer.#ctor(Eneta.Examples.CodeContracts.Testable.IRandomGenerator)">       <summary>             Constructor of Randomizer. Initializes Randomizer class.             </summary>       <param name="generator">Instance of random number generator.</param>     </member>     <member name="M:Eneta.Examples.CodeContracts.Testable.Randomizer.GetRandomFromRangeContracted(System.Int32,System.Int32)">       <summary>             Returns random integer in given range.             </summary>       <param name="min">Minimum value of random integer.</param>       <param name="max">Maximum value of random integer.</param>       <requires description="Min must be less than max" exception="T:System.ArgumentOutOfRangeException">                 min &lt; max</requires>       <exception cref="T:System.ArgumentOutOfRangeException">                 min &gt;= max</exception>       <ensures description="Return value is out of range">                 Contract.Result&lt;int&gt;() &gt;= min &amp;&amp;                 Contract.Result&lt;int&gt;() &lt;= max</ensures>     </member>   </members> </doc> As you can see then code contracts are pretty well documented. Messages that I provided with code contracts are also available in documentation. If I wrote very good and informative messages then these messages are very useful also in contracts documentation. Code contracts and Sandcastle Sandcastle knows nothing about code contracts by default. There is separate package of file for Sandcastle that is provided you by code contracts installation. You can read from code contracts manual: “Sandcastle (http://www.codeplex.com/Sandcastle) is a freely available tool that generates help les and web sites describing your APIs, based on the XML doc comments in your source code. The CodeContracts install contains a set of les that can be copied over a Sandcastle installation to take advantage of the additional contract information. The produced documentation adds a contract section to methods with declared requires and/or ensures. In order for Sandcastle to produce Contract sections, you need to patch a number of files in its installation. Please refer to the Sandcastle Readme.txt found under Start Menu/CodeContracts/Sandcastle for instructions. A future release of Sandcastle will hopefully support contract sections without the need for this patching step.” Integrating code contracts documentation to Sandcastle will be one of my next postings about code contracts. Conclusion if you are using code documentation then documentation about code contracts can be added to documentation very easily. All you have to do is to enable XML-documentation for contracts and build your project. Later you can use Sandcastle files provided by code contracts installer to integrate contracts documentation to your output documentation package.

  Read the article

• What should be included in risk management section of software's architecture documentation?

  - by Limbo Exile

  I am going to develop a Java application (a Spring Web application that will be used to extract data from various data sources) and I want to include risk management of the software in the architecture documentation. By risk management (I am not sure if this is the right name) I mean documenting possibilities of what can go wrong with the software and what to do in those cases. At first I tried to draft some lists, including things like database performance decrease, change of external components that the software interacts with, security breaches etc. But as I am not an experienced developer I cannot rely on those drafts, I don't think they are exhaustive. I searched web hoping to find something similar to the Joel Test or to find any other resource that will cite the most popular causes of problems that should be included and analyzed in risk management documentation, but I haven't found much. Finally, my question is: What should be included in risk management section of software's architecture documentation?

  Read the article

• How do you write straight to the point documentation without looking sloppy and informal?

  - by James

  I'm currently at a contract position and am looking to add to the documentation of the projects I worked on, to assist the next hiree taking over my projects. The documentation I received was overly technical (i.e. references code right away, references replacing certain values on certain lines, no high level description at all) How do I write documentation in simple plain English that is of actual benefit without looking sloppy? I find it difficult in areas such as outlining a system's flaws without coming off as judgmental, but still emphasize the severity of how detrimental some of the flaws are.

  Read the article

• Ruby core documentation quality

  - by karatedog

  I'm relatively new to Ruby and have limited time therefore I try out simple things. Recently I needed to create a file and because I'm lazy as hell, I run to Google. The result: File.open(local_filename, 'w') {|f| f.write(doc) } Shame on me, it is very straightforward, should have done it myself. Then I wanted to check what ruby magic the File class' methods offer or if there's any 'simplification' when invoking those methods, so I headed for the documentation here, and checked for the File class. 1.8.6 documentation presents me with "ftools.rb: Extra tools for the File class" under 'File' class, which is not what I'm looking for. 1.8.7 documentation seems OK for 'File' class, there are a plethora of methods. Except 'open'. 1.9 documentation finally shows me the 'open' method. And I had an almost same tour with Net::HTTP. Do I exaggerate when I think good old Turbo Pascal's 7.0 documentation was better organized than Ruby documentation is right now? Is there any other source for the uninitiated to collect knowledge? Or is it possible that I just tumbled into a documentation hole and the rest are super-brilliant-five-star organized? Thanks

  Read the article

• Free web-based software for team collaboration/documentation

  - by Jason Antman

  Looking for some advice here, as my search has turned up to be pretty fruitless. My group (9 people - SAs, programmers, and two network guys) is looking for some sort of web tool to... ahem... "facilitate increased collaboration" (we didn't use a buzzword generator, I swear). At the moment, we have an unified ticketing system that's braindead, but is here to stay for political/logistical reasons. We've got 2 wikis ("old" and "new"), neither of which fulfill our needs, and are therefore not used very often. We're looking for a free (as in both cost and open source) web-based tool. Management side: Wants to be able to track project status, who's doing what, whether deadlines are being met, etc. Doesn't want full-fledged "project management" app, just something where we can update "yeah this was done" or "waiting for Bob to configure the widgets". TeamBox (www.teambox.com) was suggested, but it seems almost too gimmicky, and doesn't meet any of the other requirements: Non-management side: - flexible, powerful wiki for all documentation (i.e. includes good tables, easy markup, syntax highlighting, etc.) - good full text search of everything (i.e. type in a hostname and get every instance anyone ever uttered that name) - task lists or ToDo lists, hopefully about to be grouped into a number of "projects" - file uploads - RSS or Atom feeds, email alerts of updates We're open to doing some customizations (adding some features, notification/feeds, searching, SVN integration, etc.) but need something F/OSS that will run under Apache. My conundrum is that most of the choices I've found so far fall into one of these categories: project management/task tracking with poor wiki/documentation/knowledge base support wiki with no task tracking support ticketing system with everything else bolted on (we already have one that we're stuck with) code-centric application (we do little "development", mostly SA work) Any suggestions? Or, lacking that, any comments on which software would be easiest to add the lacking features to (hopefully ending up with something that actually looks good and works well)?

  Read the article

• good c++ documentation design example?

  - by Eye of Hell

  Hello. I'm tuning documentation generator for internal purpose that generates HTML documentation for C++ classes and methods. Is it any example available of good HTML documentation design? MSDN ( like this ) looks kinda outdated, same is doxygen / javadoc / sphinx results. Anyone ever see an documentation that looks REALLY good?

  Read the article

• Corporate Wiki Organization - Technical Documentation

  - by Dave Jarvis

  Corporations have documents describing various aspects of their technical systems, including: Custom Applications Custom Development Frameworks Third Party Applications Accounting Bug Tracking Network Management How To Guides User Manuals Web Browsers Software Tools Development IDEs Graphics GIMP xv Text Editing File Transfer ncFTP WinSCP Hardware Servers Web Database Exchange File Network Devices Printers Drawings If you had to use a Wiki to manage the documentation, what other items would you add to the list, and how would you organize it? (For example, would Software Tools make more sense under Third Party Applications?) A few constraints: The structure should not go beyond three levels deep. Avoid the word "and" in favour of two different categories. Keep the structure general: it should appy as broadly as possible. Target audience is primarily technical, but could be visible by anyone.

  Read the article

• Does relying on intellisense and documentation a lot while coding makes you a bad programmer? [duplicate]

  - by sharp12345

  This question already has an answer here: Forgetting basic language functions due to use of IDE, over reliance? [duplicate] 4 answers Is a programmer required to learn and memorize all syntax, or is it ok to keep handy some documentation? Would it affect the way that managers look at coders? What are the downside of depending on intellisense and auto-complete technologies and pdf documentation?

  Read the article

• dvdauthor documentation?

  - by rascher

  Where is the rest of the dvdauthor documentation? If you read it, many functions and attributes have no descriptions (like commandline options or XML tags.) Other programs, however, use those tags. Has someone written a guide that fills in the gaps?

  Read the article

• Corporate Wiki Organization - Technical Documentation

  - by Dave Jarvis

  Corporations have documents describing various aspects of their technical systems, including: Custom Applications Custom Development Frameworks Third Party Applications Accounting Bug Tracking Network Management How To Guides User Manuals Software Tools Web Browsers Development IDEs Graphics GIMP xv Text Editing File Transfer ncFTP WinSCP Hardware Servers Web Database Exchange File Network Devices Printers If you had to use a Wiki to manage the documentation, what other items would you add to the list, and how would you organize it? (For example, would Software Tools make more sense under Third Party Applications?) A few constraints: The structure should not go beyond three levels deep. Avoid the word "and" in favour of two different categories. Keep the structure general: it should appy as broadly as possible. Target audience is primarily technical, but could be visible by anyone.

  Read the article

< Previous Page | 1 2 3 4 5 6 7 8 9 10 11 12  | Next Page >