Search Results

Search found 8543 results on 342 pages for 'documentation'.

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

  • Where to put code documentation?

    - by Patrick
    I am currently using two systems to write code documentation (am using C++): Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen is run on the sources so the output can be seen in a web browser Overview pages (describing a set of classes, the structure of the application, example code, ...) is added to a Wiki I personally think that this approach is easy because the documentation about members and classes is really close to the code, while the overview pages are really easy to edit in the Wiki (and it's also easy to add images, tables, ...). A web browser allows you to see both documentations. My co-worker now suggests to put everything in Doxygen, because we can then create one big help file with everything in it (using either Microsoft's HTML WorkShop or Qt Assistant). My concern is that editing Doxygen-style documentation is much harder (compared to Wiki), especially when you want to add tables, images, ... (or is there a 'preview' tool for Doxygen that doesn't require you to generate the code before you can see the result?) What do big open-source (or closed source) projects use to write their code documentation? Do they also split this up between Doxygen-style and a Wiki? Or do they use another system? What is the most appropriate way to expose the documentation? Via a Web server/browser, or via a big (several 100MB) help file? Which approach do you take when writing code documentation?

    Read the article

  • How to keep word document, html and pdf documentation aligned

    - by dendini
    Is there a way to write documentation in a WYSIWYG editor which can then export into HTML, WORD and PDF and keep copies synchronized? This documentation are mostly technical notes and some contextual help for some softwares so they must contain images and some styling, they are not programmer's documentation (API list or functions list) for which probably a program like Javadoc or Doxygen would be the best choice. For example how do companies with hundreds different software lines and thousands of programmers deal with this? I have several solutions but they all seem lacking in some aspect: Latex/Tex : very good pdf and html export, not very user friendly and no full-blown WYSIWYG editor available. LibreOffice/OpenOffice : full blown WYSIWYG editor however html export not so good (need to edit manually exported html which needs to be maintained separately ) Mediawiki or any other wiki : could be keeping documentation in wikitext format, so html is automatically generated, pdf exportation is quite good with many available plugins. Again however need some formation for the staff to use it and need to setup a server for this. Notice I'm not asking for software A vs software B, I'm asking for general advice, big companies procedures for documentation and yes some software product names if available.

    Read the article

  • SDLC/Deployment/Documentation ERP/framework that minimizes developer misery

    - by foampile
    I was wondering if there are favorite SDLC/Deployment/Documentation/Versioning ERP/frameworks that work with popular SDLC methodologies, such as Agile, that minimize developer exposure to what most programmer hate to do most -- PAPERWORK ? Often, release management is extremely inefficient and there is a lot of data duplication across documents that are required to accompany changes -- e.g. when submitting a deployment request, I must list all files and their revisions from source control -- but why is that necessary if every file revision I check in is pinned to a work order and a deployment request is just a list of work orders -- such info should be able to be pulled from the system automatically without me needing to extract it and report it. And then there is a backout plan -- well just do everything in reverse from what you did to deploy -- why do you need specific instructions? Similar applies for documentation... So I am curious if there is an overall, all-encompassing ERP that includes source control and minimizes paperwork by sharing centralized data across different documents (such as documentation being pulled from javadoc without needing to write it separately) associated with SDLC yet does not compromise structure and control over the code base and release management.

    Read the article

  • documentation of typescript code

    - by Max Beikirch
    my question is rather short: How do I document typescript code properly? I found out that for projects becoming bigger and bigger, it is important to look at a function and immediately know parameters, what it returns and side-effects etc. It is tiring to have just a bunch of comments before a function, most of the time these 'blocks' even look differently in style. What I am looking for is a documentation tool like javadoc or doxygen for typescript. Is there anything out there? Or is it possible to 'abuse' a documentation tool and get it to work with typescript?

    Read the article

  • Comprehensive system for documentation and handoff of developer project

    - by Uzumaki Naruto
    I work on a technology team that typically develops projects for a period of time, and then hands off to other groups for long-term maintenance and improvements. My team currently uses ad hoc methods of handing off documentations, such as diagrams, API references, etc. Is there a open source solution (or even proprietary one) that enables us to manage: Infrastructure/architecture/software diagrams API documentation Directory structures/file structures Overall documentation summaries in one place? E.g., instead of using multiple systems like Swagger, Wikis, etc. - is there a solution that can seamlessly combine all of these? And enable us to generate a package including all 4 key items with one click to hand off to other teams.

    Read the article

  • PDF or ebook Java API documentation

    - by AmaDaden
    Since I have a long train ride to and from work I was wondering if there is a version of the Java API documentation floating around that I could put on my Kindle. It would be nice on the rare occasion I get something in my head that I want to think about some more. I know I can browse the web through the Kindle but coverage is spotty and slow. I know that the api docs are not really designed for a sequential reading format but I'm curious to see if anyone else has thought about this and given it a shot.

    Read the article

  • Encourage the use of markup files as documentation in enterprise [closed]

    - by linquize
    To make it eaiser to do version control and diff files of documentation, use markup files, such as HTML: html/xhtml, XML: docbook, Wiki: markdown to replace doc/docx. docx is too complex and lengthy. For html, no extra document generation required. Programmers can write html directly and end users / managers can use any web browsers to view the document. For custom XML or Wiki formats, viewers are required to view the document or converters are used to export to pdf/doc. Is such move becoming popular in enterprise context? Why or why not?

    Read the article

  • Seeking advice on system documentation

    - by Shadders
    I have a rating engine (it is basically an algorithm) which when I started had no formal documentation. We have created a functional specification/decomposition which is our business level document but now I need something more technical (a technical specification). What I am struggling to understand is what that document looks like, what format it should be in and to what level of detail we should go into. We are in the process of commenting all of the code. We also have a rough document called a Blueprint which reflects the flow of the model and is written in pseudo code. Is the combination of this blueprint and the model comments sufficient as a Technical Specification?

    Read the article

  • How to Automate your Database Documentation

    - by Jonathan Hickford
    In my previous post, “Automating Deployments with SQL Compare command line” I looked at how teams can automate the deployment and post deployment validation of SQL Server databases using the command line versions of Red Gate tools. In this post I’m looking at another use for the command line tools, namely using them to generate up-to-date documentation with every database change. There are many reasons why up-to-date documentation is valuable. For example when somebody new has to work on or administer a database for the first time, or when a new database comes into service. Having database documentation reduces the risks of making incorrect decisions when making changes. Documentation is very useful to business intelligence analysts when writing reports, for example in SSRS. There are a couple of great examples talking about why up to date documentation is valuable on this site:  Database Documentation – Lands of Trolls: Why and How? and Database Documentation Using SQL Doc. The short answer is that it can save you time and reduce risk when you need that most! SQL Doc is a fast simple tool that automatically generates database documentation. It can create documents in HTML, Word or pdf files. The documentation contains information about object definitions and dependencies, along with any other information you want to associate with each object. The SQL Doc GUI, which is included in Red Gate’s SQL Developer Bundle and SQL Toolbelt, allows you to add additional notes to objects, and customise which objects are shown in the docs.  These settings can be saved as a .sqldoc project file. The SQL Doc command line can use this project file to automatically update the documentation every time the database is changed, ensuring that documentation that is always up to date. The simplest way to keep documentation up to date is probably to use a scheduled task to run a script every day. However if you have a source controlled database, or are using a Continuous Integration (CI) server or a build server, it may make more sense to use that instead. If  you’re using SQL Source Control or SSDT Database Projects to help version control your database, you can automatically update the documentation after each change is made to the source control repository that contains your database. To get this automation in place,  you can use the functionality of a Continuous Integration (CI) server, which can trigger commands to run when a source control repository has changed. A CI server will also capture and save the documentation that is created as an artifact, so you can always find the exact documentation for a specific version of the database. This forms an always up to date data dictionary. If you don’t already have a CI server in place there are several you can use, such as the free open source Jenkins or the free starter editions of TeamCity. I won’t cover setting these up in this article, but there is information about using CI servers for automating database tasks on the Red Gate Database Delivery webpage. You may be interested in Red Gate’s SQL CI utility (part of the SQL Automation Pack) which is an easy way to update a database with the latest changes from source control. The PowerShell example below shows how to create the documentation from a database. That database might be your integration database or a shared development database that is always up to date with the latest changes. $serverName = "server\instance" $databaseName = "databaseName" # If you want to document multiple databases use a comma separated list $userName = "username" $password = "password" # Path to SQLDoc.exe $SQLDocPath = "C:\Program Files (x86)\Red Gate\SQL Doc 3\SQLDoc.exe" $arguments = @( "/server:$($serverName)", "/database:$($databaseName)", "/username:$($userName)", "/password:$($password)", "/filetype:html", "/outputfolder:.", # "/project:$args[0]", # If you already have a .sqldoc project file you can pass it as an argument to this script. Values in the project will be overridden with any options set on the command line "/name:$databaseName Report", "/copyrightauthor:$([Environment]::UserName)" ) write-host $arguments & $SQLDocPath $arguments There are several options you can set on the command line to vary how your documentation is created. For example, you can document multiple databases or exclude certain types of objects. In the example above, we set the name of the report to match the database name, and use the current Windows user as the documentation author. For more examples of how you can customise the report from the command line please see the SQL Doc command line documentation If you already have a .sqldoc project file, or wish to further customise the report by including or excluding specific objects, you can use this project on the command line. Any settings you specify on the command line will override the defaults in the project. For details of what you can customise in the project please see the SQL Doc project documentation. In the example above, the line to use a project is commented out, but you can uncomment this line and then pass a path to a .sqldoc project file as an argument to this script.  Conclusion Keeping documentation about your databases up to date is very easy to set up using SQL Doc and PowerShell. By using a CI server to run this process you can trigger the documentation to be run on every change to a source controlled database, and keep historic documentation available. If you are considering more advanced database automation, e.g. database unit testing, change script generation, deploying to large numbers of targets and backup/verification, please email me at [email protected] for further script samples or if you have any questions.

    Read the article

  • What are the preferred documentation tools for the major programming languages?

    - by Dave Peck
    I'm interested in compiling a list of major programming languages and their preferred documentation toolsets. To scope this a bit: The exact structure of the answer may vary from language to language, but there appear to be two aspects common to all languages: (1) in-code syntax for documentation, and (2) documentation generators that make use of said syntax. There are also cases where generators are used independent of code. For example, tutorial-style documentation is common in the Python world and is often disconnected from underlying code. Many languages have multiple commonly-used documentation strategies and tool chains, and I'd love to capture this. Finally, there are cross-language tools like Doxygen that also have some traction and would be worth noting here. Here are some obvious target languages to start with: Python, Ruby, Java, C#, PHP, Objective-C, C/C++, Haskell, Erlang, Scala, Clojure If this question catches on, I'll try and keep this section updated with the most recent list. Thanks!

    Read the article

  • Hyperlinked, externalized source code documentation

    - by Dave Jarvis
    Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code, rather than as a separate document? Given the expansive real-estate afforded to modern development environments (high-resolution monitors, dual-monitors, etc.), an IDE could provide semi-lock-step panels wherein source code is visually separated from -- but intrinsically linked to -- its corresponding comments. For example, developers could write source code comments in a hyper-linked markup language (linking to additional software requirements), which would simultaneously prevent documentation from cluttering the source code. What shortcomings would inhibit such a software development mechanism? A mock-up to help clarify the question: When the cursor is at a particular line in the source code (shown with a blue background, above), the documentation that corresponds to the line at the cursor is highlighted (i.e., distinguished from the other details). As noted in the question, the documentation would stay in lock-step with the source code as the cursor jumps through the source code. A hot-key could switch between "documentation mode" and "development mode". Potential advantages include: More source code and more documentation on the screen(s) at once Ability to edit documentation independently of source code (regardless of language?) Write documentation and source code in parallel without merge conflicts Real-time hyperlinked documentation with superior text formatting Quasi-real-time machine translation into different natural languages Every line of code can be clearly linked to a task, business requirement, etc. Documentation could automatically timestamp when each line of code was written (metrics) Dynamic inclusion of architecture diagrams, images to explain relations, etc. Single-source documentation (e.g., tag code snippets for user manual inclusion). Note: The documentation window can be collapsed Workflow for viewing or comparing source files would not be affected How the implementation happens is a detail; the documentation could be: kept at the end of the source file; split into two files by convention (filename.c, filename.c.doc); or fully database-driven By hyperlinked documentation, I mean linking to external sources (such as StackOverflow or Wikipedia) and internal documents (i.e., a wiki on a subdomain that could cross-reference business requirements documentation) and other source files (similar to JavaDocs). Related thread: What's with the aversion to documentation in the industry?

    Read the article

  • A big flat text file or a HTML site for language documentation?

    - by Bad Sector
    A project of mine is a small embeddable Tcl-like scripting language, LIL. While i'm mostly making it for my own use, i think it is interesting enough for others to use, so i want it to have a nice (but not very "wordy") documentation. So far i'm using a single flat readme.txt file. It explains the language's syntax, features, standard functions, how to use the C API, etc. Also it is easy to scan and read in almost every environment out there, from basic text-only terminals to full-fledged high-end graphical desktop environments. However, while i tried to keep things nicely formatted (as much as this is possible in plain text), i still think that being a big (and growing) wall of text, it isn't as easy on the eyes as it could be. Also i feel that sometimes i'm not writing as much as i want in order to avoid expanding the text too much. So i thought i could use another project of mine, QuHelp, which is basically a help site generator for sites like this one with a sidebar that provides a tree of topics/subtopics and offline full text search. With this i can use HTML to format the documentation and if i use QuHelp for some other project that uses LIL, i can import LIL's documentation as part of the other project's documentation. However converting the existing documentation to QuHelp/HTML isn't a small task, especially when it comes to functions (i'll need to put more detail on them than what currently exists in the readme.txt file). Also it loses the wide range of availability that it currently has (even if QuHelp's generated code degrades gracefully down to console-only web browsers, plain text is readable from everywhere, including from popular editors such as Vim and Emacs - i had someone once telling me that he likes LIL's documentation because it is readable without leaving his editor). So, my question is simply this: should i keep the documentation as it is now in the form of a single readme.txt file or should i convert it to something like the site i mentioned above? There is also the option to do both, but i'm not sure if i'll be able to always keep them in sync or if it is worth the effort. After asking around in IRC i've got mixed answers: some liked the wide availability of the single text file, others said that it is looks as bad as a man page (personally i don't mind that - i can read man pages just fine - but other people might have issues reading them). What do you think?

    Read the article

  • SQL SERVER – Download SQL Server Product Documentation

    - by pinaldave
    Today I just returned from Bangalore User Group Meeting. Attending User Group meeting is indeed fun and really great experience. The best part of the User Group is meeting like minded people and have a great conversation with them. During the meeting I was asked why one has to go online to access SQL Server Product Documentation. I can clearly see there can be many reasons for why one wants the documentation to be available offline. The reasons can be anything but not limited to Company Firewall No Internet (power failure, on road or disaster) Internet Bandwidth Limitatoin Company Proxy Issues … and much more… In this kind of situation one needs documentation which is offline and easily available in local computer. The Microsoft SQL Server 2012 setup installs only the Help Viewer and related components for managing Help settings. Setup does not directly install any documentation. All of the SQL Server documentation is available online. Well, Microsoft has recently released Production Documentation available for offline users as well. You just have to download the executable file and follow all the instructions. Please follow the link below for download of the file. There is detailed instruction on how to download and install the documentation offline. Product Documentation for Microsoft SQL Server 2012 Reference: Pinal Dave (http://blog.sqlauthority.com) Filed under: PostADay, SQL, SQL Authority, SQL Documentation, SQL Download, SQL Query, SQL Server, SQL Tips and Tricks, T SQL, Technology

    Read the article

  • Open Source Web-based CMS for writing and managing API documentation

    - by netcoder
    This is a question that have somewhat been asked before (i.e.: How to manage an open source project's documentation). However, my question is a little different because: We're not developing open source software, but proprietary software The documentation has to be hand-written, because we do not want to publish the actual software API documentation, but only the public API documentation I do want developers and project managers to write the documentation collaboratively Obviously, wikis are a solution, but they're very generic. I'm looking for a more specialized tool for this job. I've looked around and found a few like Adobe Robohelp, SaaS solutions and such, but I'd like to know if any open source software exists for that purpose. Do you know any Open Source Web-based CMS for writing and managing API and software documentation?

    Read the article

  • SQLAuthority News – Microsoft SQL Server Protocol Documentation Download

    - by pinaldave
    The Microsoft SQL Server protocol documentation provides detailed technical specifications for Microsoft proprietary protocols (including extensions to industry-standard or other published protocols) that are implemented and used in Microsoft SQL Server to interoperate or communicate with Microsoft products. The documentation includes a set of companion overview and reference documents that supplement the technical specifications with conceptual background, overviews of inter-protocol relationships and interactions, and technical reference information. Microsoft SQL Server Protocol Documentation Reference : Pinal Dave (http://blog.SQLAuthority.com) Filed under: SQL, SQL Authority, SQL Documentation, SQL Download, SQL Query, SQL Server, SQL Tips and Tricks, T SQL, Technology

    Read the article

  • Using automated bdd-gui-tests to keep user-documentation-screenshots up do date?

    - by k3b
    Are there developpers out there, who (ab)use the CaptureScreenshot() function of their automated gui-tests to also create uptodate-screenshots for the userdocumentation? Background: Whithin the lifetime of an application, its gui-elements are constantly changing. It makes a lot of work to keep the userdocumentation uptodate, especially if the example data in the pictures should match the textual description. If you already have automated bdd-gui-tests why not let them take screenshots at certain points? I am currently playing with webapps in dotnet+specflow+selenium, but this topic also applies to other bdd-engines (JRuby-Cucumber, mspec, rspec, ...) and gui-test-Frameworks (WaitN, WaitR, MsWhite, ....) Any experience, thoughts or url-links to this topic would be helpfull. How is the cost/benefit relation? Is it worth the efford? What are the Drawbacks? See also: Is it practical to retroactively write specifications documenting a system via automated acceptance tests?

    Read the article

  • Is extensive documentation a code smell?

    - by Griffin
    Every library, open-source project, and SDK/API I've ever come across has come packaged with a (usually large) documentation file, and this seems contradictory to the wide-spread belief that good code needs little to no comments. What separates documentation from this programming methodology? a one to two page overview of a package seems reasonable, but elegant code combined with standard intelisense should have theoretically deprecated the practice of documentation by now IMO. I feel like companies only create detailed documentation and tutorials because its what they've always done. Why should developers have to constantly be searching through online documentation in order to learn how to do things when such information should be intrinsic to the classes, methods and namespaces?

    Read the article

  • Are unit tests really used as documentation?

    - by stijn
    I cannot count the number of times I read statements in the vein of 'unit tests are a very important source of documentation of the code under test'. I do not deny they are true. But personally I haven't found myself using them as documentation, ever. For the typical frameworks I use, the method declarations document their behaviour and that's all I need. And I assume the unit tests backup everything stated in that documentation, plus likely some more internal stuff, so on one side it duplicates the ducumentation while on the other it might add some more that is irrelevant. So the question is: when are unit tests used as documentation? When the comments do not cover everything? By developpers extending the source? And what do they expose that can be useful and relevant that the documentation itself cannot expose?

    Read the article

  • What does your Technical Documentation look like?

    - by Rachel
    I'm working on a large project and I would like to put together some technical documentation for other members of the team and for new programmers joining the project. What sort of documentation should I have? Just /// code comments or some other file(s) explaining the architechure and class design? I've never really done documentation except the occasional word doc to go with smaller apps, and I think this project is too large to doc in a single word file.

    Read the article

  • How do you balance documentation requirements with Agile developments

    - by Jeremy
    In our development group there is currently discussions around agile and waterfal methodology. No-one has any practical experience with agile, but we are doing some reading. The agile manifesto lists 4 values: Individuals and interactions over processes and tools Working software over comprehensive documentation Customer collaboration over contract negotiation Responding to change over following a plan We are an internal development group developing applications for the consumption of other units in our enterprise. A team of 10 developers builds and releases multiple projects simultanously, typically with 1 - maybe 2 (rarely) developer on each project. It seems to be that from a supportability perspective the organization needs to put some real value on documentation - as without it, there are serious risks with resourcing changes. With agile favouring interactions, and software deliverables over processes and documentation, how do you balance that with the requirements of supportable systems and maintaining knowledge and understanding of how those systems work? With a waterfall approach which favours documentation (requirements before design, design specs before construction) it is easy to build a process that meets some of the organizational requirements - how do we do this with an agile approach?

    Read the article

  • Support / Maintenance documentation for development team

    - by benwebdev
    Hi, I'm working in the Development dept (around 40 developers) for a large E-Commerce company. We've grown quickly but have not evolved very well in the field of documenting our work. We work with an Agile / Scrum-like methodology with our development and testing but documentation seems to be neglected. We need to be able to make documentation that would aid a developer who hasnt worked on our project before or was new to the company. We also have to create more high level information for our support department to explain any extra config settings and fixes of known issues that may arise, if any. Currently we put this in a badly put together wiki, based on an old Sharepoint / TFS site. Can anyone suggest some ideal links or advice on improving the documentation standard? What works in other companies? Has anyone got avice on developing documentation as part of an agile process? Many thanks, ben

    Read the article

  • What makes a good developer / system documentation?

    - by deamon
    Much time is wasted to get new developers started with existing software systems, because there is no good documenation. But what makes a system documentation good? One thing is a good API documentation like the Java API doc, but how to transfer the "bigger picture" and other things that cannot be placed in the API doc? One constraint is that it should not be to hard and time consuming to write the docs, because that is one reason why it is omitted so often. So, what makes documentation good?

    Read the article

  • Studies on code documentation productivity gains/losses

    - by J T
    Hi everyone, After much searching, I have failed to answer a basic question pertaining to an assumed known in the software development world: WHAT IS KNOWN: Enforcing a strict policy on adequate code documentation (be it Doxygen tags, Javadoc, or simply an abundance of comments) adds over-head to the time required to develop code. BUT: Having thorough documentation (or even an API) brings with it productivity gains (one assumes) in new and seasoned developers when they are adding features, or fixing bugs down the road. THE QUESTION: Is the added development time required to guarantee such documentation offset by the gains in productivity down-the-road (in a strictly economical sense)? I am looking for case studies, or answers that can bring with them objective evidence supporting the conclusions that are drawn. Thanks in advance!

    Read the article

  • How do I include Implementation and Usage Documentation in one file

    - by Angelo.Hannes
    There are two types of documentation. One type, the Implementation Documentation, contains information about specific implementation of a construct (eg. Class, Method, etc.). It is targeted to the future me, maintainer, debugger and so on. And there is Usage Documentation, containing information how to use a provided api. It does not contain information about specific implementation and is targeted to users of the api. How do I include both of them in one file? (Or do I include both of them in one file? And if not, what type belongs into the source file?) Are there special techniques, using java-doc and/or best practices?

    Read the article

  • Writting Rails project documentation

    - by potapuff
    Hi to all. Give me an example, that's you can describe as "well documented project on Rails", or "best practices of making documentation for Rails project" (with link to github, or other same site, if it possible). And, what tool's you prefer to use for writing documentation of your project?

    Read the article

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