Search Results

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

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

• What tool/framework to use for technical documentation?

  - by Pangea

  We develop products and frameworks to be used with in our organization. I am looking for programmer friendly documentation tools. I have researched on few options sometime back but couldn't decide which one to use. I am looking for suggestions from the people who already used these tools. docbook: springframework and hibernate use this format and this looks good. but I believe they have customized the default xslt/stylesheet. Can I copy and use their xslt and css (ofcourse with colors and images changed). Can I integrate the doc generation using maven? wiki: this is not friendly to the technical document writers and the documentation doesn't look professional. versioning is also not possible I believe word docs: this is what we use currently but it is hard to link and reuse common documents. DITA?

  Read the article

• Marking "example usage" in code documentation

  - by Ross

  What the best practice of placing example usage in code documentation? Is there a standardised way? With an @usage or @notes? For example: /** * My Function * @param object id anObject * @usage a code example here... */ function foo(id) { } or /** * My Function * @param object id anObject * @notes a code example here, maybe? */ function foo(id) { } I know this question should dependent on the documentation generator, but any heads up appreciated... I'm trying to get into the habit of using proper style. When time allow I'll get more into the generators. (I've experimented with Doxygen.) I often use AS3, JS, Obj-C, C++. Thanks

  Read the article

• Documentation utility for OpenEdge ABL

  - by glowcoder

  I have a large system in OpenEdge ABL that could use some documentation-love. Currently a team member is working on a utility that can find methods and functions and make some "Javadoc-esque" html pages out of it. It's pretty rough around the edges. Okay, it's like sawblades around the edges. I'm trying to find something like Javadoc or Doxygen that is capable of parsing OpenEdge ABL to generate some kind of API documentation. I know the market for OpenEdge isn't the best, but there is a lot of stuff that's passed along by word of mouth. It's difficult to search for because it used to be called "Progress" which throws off your search queries with non-relevant information. I'm also open to a system that lets you define the regex's to look for to define your own syntax. Then it parses and gives you an output based on that. Thanks!

  Read the article

• What are the benefits and drawback of documentation vs tutorials vs video tutorials [closed]

  - by Cat

  Which types of learning resources do you find the most helpful, for which kinds of learning and/or perhaps at specific times? Some examples of types of learning you could consider: When starting to integrate a new SDK inside an existing codebase When learning a new framework without having to integrate legacy code When digging deeper into an already-used SDK that you may not know very well yet For example - (video) tutorials are usually very easy to follow and tells a story from beginning to end to get results, but will nearly always assume starting from scratch or a previous tutorial. Therefore such a resource is useful for quick learning if you don't have legacy code around, but less so if you have to search for the best-fit to the code you already have. SDK Documentation on the other hand is well-structured but does not tell a story. It is more difficult to get to a specific larger result with documentation alone, but it is a better fit when you do have legacy code around and are searching for perhaps non-obvious ways of employing the SDK or library. Are there other forms of resources that you find useful, such as interactive training?

  Read the article

• Lua & Javascript documentation generation

  - by Tiddo

  I am in the beginning phase of create a mobile MMO with my team. The server software will be written in JavaScript using NodeJS, and the client software in Lua using Corona. We need a tool to auto-generate documentation for both the server-side and client-side code. Are there any tools which can generate documentation for both Lua and Javascript? And as a bonus: we are hosting our project on Bitbucket and the Bitbucket Wiki uses the Creole markup language. So if it's possible I want the tool to export to Creole.

  Read the article

• Humor in Documentation

  - by Lex Fridman

  Is a small amount of lighthearted wording or humor acceptable in source code documentation? For example, I have an algorithm that has a message hop around a graph (network) until its path forms a cycle. When this happens it is removed from the queue of the node it last resided on which removes it from memory. I write that in a comment, and finish the comment with "Rest in peace, little guy". That serves very little documenting purpose, but it cheers me up a bit, and I imagine it might cheer up other people I'm working with as they read through the code. Is this an acceptable practice, or should my in-code documentation resemble as much as possible the speeches of 2004 United States presidential candidate John Kerry? ;-)

  Read the article

• Is gettext appropriate for internationalizing user help documentation?

  - by Richard JP Le Guen

  On my project, we have po files to internationalize/translate various labels, error messages, button-text etc. We also have separate po files for the entirety of our help documentation, which is included in the product. Is this an appropriate use of gettext - putting entire documents in po files as opposed to just labels and messages? The format has been made all the more complicated because sometimes (for tooltips or "what's this" icons) only a small part of the help doc is needed, resulting in single phrases/paragraphs being entries in the po file, which are then concatenated together when the user views the help... making the actual act of translation challenging. Is there a better way to internationalize end user help documentation?

  Read the article

• Humor in Documentation

  - by Lex Fridman

  Is a small amount of lighthearted wording or humor acceptable in source code documentation? For example, I have an algorithm that has a message hop around a graph (network) until its path forms a cycle. When this happens it is removed from the queue of the node it last resided on which removes it from memory. I write that in a comment, and finish the comment with "Rest in peace, little guy". That serves very little documenting purpose, but it cheers me up a bit, and I imagine it might cheer up other people I'm working with as they read through the code. Is this an acceptable practice, or should my in-code documentation resemble as much as possible the speeches of 2004 presidential candidate John Kerry? ;-)

  Read the article

• Tool to Create Annotated Directory Structure Documentation

  - by Millhouse

  I've got a moderately complicated application that has been developed primarily by me, and I'm getting ready to bring a few more developers in, and I'm thinking of various forms of documentation that might be helpful. I want to communicate information about the directory structure/layout of the project so the new guys will know where to look for things when they are getting started and as they add features, know where to put new files etc., so we can keep things organized and consistent. Is there any tool out there can create something a little more sophisticated than just a plain text document? I'm thinking of something that looks similar to Windows Explorer with a directory structure on the left in a panel and then when you click on a particular folder, you would be able to view some text or HTML that describes the folder in the right hand panel. Oh, and development will be done on Windows, but cross platform would be nice.

  Read the article

• Documentation of a software project

  - by anijhaw

  I am working with a team that works on a very large software project, we have tons of Documentation that is written in MS WORD format with nohyperlinked indexes, no search ability. Everyday we waste our time trying to find the exact document or reference. I was thinking if there was way or even a professional tool that would convert all this into a wiki format and maybe with a little manual (painful) help be organised into something that improves the accessibility. I use Google Desktop Search to make my life a little easier but its not the best solution I just want to know if any of you faced similar problems and possible solutions to this issue.

  Read the article

• Differences in documentation for sys.dm_exec_requests

  - by AaronBertrand

  I've already complained about this on Connect ( see #641790 ), but I just wanted to point out that if you're trying to make sense of the sys.dm_exec_requests document and what it lists as the commands supported by the percent_complete column, you should check which version of the documentation you're reading. I noticed the following discrepancies. I can't explain why certain operations are missing, except that the Denali topic was generated from the 2008 topic (or maybe from the 2008 R2 topic before...(read more)

  Read the article

• Should generated documentation go in version control history?

  - by dukeofgaming

  I'm against compiled stuff going into version control, specially when it comes to compiled binaries, however, my principles are now in question after adding doxygen support for a project. Should the hundreds of files generated by doxygen go into version control?, what is the recommended practice here?, I think the ideal would be automating the process in a server that publishes that documentation at the same time, however, there is no such server now nor there will be for some time.

  Read the article

• Differences in documentation for sys.dm_exec_requests

  - by AaronBertrand

  I've already complained about this on Connect ( see #641790 ), but I just wanted to point out that if you're trying to make sense of the sys.dm_exec_requests document and what it lists as the commands supported by the percent_complete column, you should check which version of the documentation you're reading. I noticed the following discrepancies. I can't explain why certain operations are missing, except that the Denali topic was generated from the 2008 topic (or maybe from the 2008 R2 topic before...(read more)

  Read the article

• Updated Master Data Services Documentation and Resources

  - by mattande

  (This post was contributed by Reagan Templin, Lead Technical Writer for the MDS Team) With the release of SQL Server 2008 R2, it’s a great time to check out the updated documentation and resources for the release, and for SQL Server 2008 R2 Master Data Services ("MDS") in particular. As you saw in the last post ( New White Papers Available ), there are some great white papers available on MSDN to get you going with MDS. Below you’ll find more information about other updated and newly published content....(read more)

  Read the article

• Commenting/In-Code Documentation Styles

  - by Maxpm

  This might be a stupid question, but it's been in the back of my head for a while and I can't find a decent answer anywhere else. I have a teacher who says we should explicitly list each parameter with a description, even if there's only one. This leads to a lot of repetition: double MyFunction(const int MyParam); // Function: MyFunction // Summary: Does stuff with MyParam. // Input: int MyParam - The number to do stuff with. // Output: MyParam with stuff done to it. When writing in-code documentation, how detailed are you?

  Read the article

• Waterfall model documentation

  - by AjmeraInfo

  I want to create a waterfall model. What do I need to do for that? What type of document are required for that?

  Read the article

• Where should a programmer explain the extended logic behind the code?

  - by SRKX

  I have developed a few quantitative libraries in C# where it is important to understand not only the classic information that goes with the XMLDoc comments (which contains basic information with the method signature) but also the mathematical formulas being use within the methods. Hence I would like to be able to include extended documentation with the code, which could contain, for example Latex formulas, graphs, and so on. Do you think such information should be included in the API documentation? Or should it be included in a dev blog for examples? Are there common tools that are usually used for this kind of purposes?

  Read the article

• Using Cucumber or RSpec+Selenium to create end user documentation?

  - by carolclarinet

  Has anyone tried creating end user (potentially online, potentially to be printed) help/documentation out of your cucumber scenarios? Or taken screenshots for use in documentation using RSpec and Selenium RC's ability to do so? For Cucumber, I'm imagining something like: Scenario: If you want to add a link Given I am on the edit blog post page When I press the "add link" button And I type in a link URL "http://stackoverflow.com" And I click "OK" Then the blog post should have 1 link Translating to the documentation: If you want to add a link, go to the edit blog post page. Press the "add link" button and type a URL, like "http://stackoverflow.com", into the link URL field. Click "OK". Would it be worth my time to try and, for one, write something to parse my Cucumber features into documentation, and two, to write/structure my Cucumber features in such a way as to create good documentation? Would the resulting documentation end up sounding really boring without much variation in the structure? Is there anything else out there like this idea? Doxygen looks like it's more for code documentation than end-user documentation. What about automatically taking screenshots? This seems like a more fruitful path-- just reuse the code that takes a screenshot when an RSpec test fails and have it take one in prescribed situations. Is there a better way to do this?

  Read the article

• Are XML Comments Necessary Documentation?

  - by Bob Horn

  I used to be a fan of requiring XML comments for documentation. I've since changed my mind for two main reasons: Like good code, methods should be self-explanatory. In practice, most XML comments are useless noise that provide no additional value. Many times we simply use GhostDoc to generate generic comments, and this is what I mean by useless noise: /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } To me, that's obvious. Having said that, if there were special instructions to include, then we should absolutely use XML comments. I like this excerpt from this article: Sometimes, you will need to write comments. But, it should be the exception not the rule. Comments should only be used when they are expressing something that cannot be expressed in code. If you want to write elegant code, strive to eliminate comments and instead write self-documenting code. Am I wrong to think we should only be using XML comments when the code isn't enough to explain itself on its own? I believe this is a good example where XML comments make pretty code look ugly. It takes a class like this... public class RawMaterialLabel : EntityBase { public long Id { get; set; } public string ManufacturerId { get; set; } public string PartNumber { get; set; } public string Quantity { get; set; } public string UnitOfMeasure { get; set; } public string LotNumber { get; set; } public string SublotNumber { get; set; } public int LabelSerialNumber { get; set; } public string PurchaseOrderNumber { get; set; } public string PurchaseOrderLineNumber { get; set; } public DateTime ManufacturingDate { get; set; } public string LastModifiedUser { get; set; } public DateTime LastModifiedTime { get; set; } public Binary VersionNumber { get; set; } public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; } } ... And turns it into this: /// <summary> /// Container for properties of a raw material label /// </summary> public class RawMaterialLabel : EntityBase { /// <summary> /// Gets or sets the id. /// </summary> /// <value> /// The id. /// </value> public long Id { get; set; } /// <summary> /// Gets or sets the manufacturer id. /// </summary> /// <value> /// The manufacturer id. /// </value> public string ManufacturerId { get; set; } /// <summary> /// Gets or sets the part number. /// </summary> /// <value> /// The part number. /// </value> public string PartNumber { get; set; } /// <summary> /// Gets or sets the quantity. /// </summary> /// <value> /// The quantity. /// </value> public string Quantity { get; set; } /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } /// <summary> /// Gets or sets the lot number. /// </summary> /// <value> /// The lot number. /// </value> public string LotNumber { get; set; } /// <summary> /// Gets or sets the sublot number. /// </summary> /// <value> /// The sublot number. /// </value> public string SublotNumber { get; set; } /// <summary> /// Gets or sets the label serial number. /// </summary> /// <value> /// The label serial number. /// </value> public int LabelSerialNumber { get; set; } /// <summary> /// Gets or sets the purchase order number. /// </summary> /// <value> /// The purchase order number. /// </value> public string PurchaseOrderNumber { get; set; } /// <summary> /// Gets or sets the purchase order line number. /// </summary> /// <value> /// The purchase order line number. /// </value> public string PurchaseOrderLineNumber { get; set; } /// <summary> /// Gets or sets the manufacturing date. /// </summary> /// <value> /// The manufacturing date. /// </value> public DateTime ManufacturingDate { get; set; } /// <summary> /// Gets or sets the last modified user. /// </summary> /// <value> /// The last modified user. /// </value> public string LastModifiedUser { get; set; } /// <summary> /// Gets or sets the last modified time. /// </summary> /// <value> /// The last modified time. /// </value> public DateTime LastModifiedTime { get; set; } /// <summary> /// Gets or sets the version number. /// </summary> /// <value> /// The version number. /// </value> public Binary VersionNumber { get; set; } /// <summary> /// Gets the lot equipment scans. /// </summary> /// <value> /// The lot equipment scans. /// </value> public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; } }

  Read the article

• What schema documentation tools exist for PostgreSQL

  - by Brad Koch

  MySQL has MySQL Workbench for designing and documenting your schema, and generates CREATE and ALTER scripts based on your design. We're looking at migrating to PostgreSQL in the near future, and we do need a practical way of documenting and modifying the schema structure. What similar tools exist for Postgres (that are OS X/Linux compatible)? Alternatively, what equivalent conventions would be followed for designing and documenting the structure of your Postgres database?

  Read the article

• Does searching documentation and samples look bad?

  - by Mick Aranha

  I am starting a new job in a company with many developers and media people, the layout of the place is open with computers around a skinny oval, I have worked in small teams and programming embedded C, the jobis for objective C I'm still in a medium stage, so I know what I don't know (haha), that means I have to google it and then implement it, So the question is how bad does it look if the guy next to you does lot of searching for coding I mean, at the end of the day I will get the job done, but want to look professional too!

  Read the article

• Generate HTML pages from some template

  - by Appu

  I have an open-source project for which I have to generate HTML pages to put on the web. I wanted to keep everything as simple HTML pages. The problem with this approach is if I need to change the design, I have to goto all the pages and change it. This will be tough as I have lot of pages. Is there some kind of HTML generators which can process simple annotated text files? This way, I can maintain the documentation and website contents as plain text files and run it through this program to generate static HTML pages. This also helps in keeping the design consistent. Any help would be great!

  Read the article

• How to document experimental or incomplete APIs like @deprecated?

  - by Michael Levy

  Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely change? (Yeah, I know, those methods shouldn't be public, yada yada yada. I didn't create my situation, I'm just trying to make the best of it.) What do people suggest? Experimental, Incomplete, something else? If I'm building javadoc documentation for this API that is still in flux, should I use the @deprecated tag or is there a better convention? To me @deprecated implies that this API is old and a newer preferred mechanism is available. In my situation, there is no alternative, but some of the methods in the API are not finished and so should not be used. At this point I cannot make them private, but I'd like to put clear warnings in the docs.

  Read the article

• I'm tasked with leading the documentation effort for an existing, entirely undocumented, software product - what resources are there to help me?

  - by Ben Rose

  I'm a software developer at a technology company. I have been tasked with leading the documentation effort for the product I work on. The goal is to produce documentation internal to developer, and the project spills over into the business side, where it covers requirements documentation. This project is challenging. Specifically, I'm dealing with a product which: - has been around for a long time, at least 6 years. - has no form of documentation other than some small, outdated pieces here and there. - has 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, is often unnecessarily complex under the covers In addition, we have not been given a lot of time to work on this project. I do not have any formal documentation or writing background, training, or experience. I have displayed some ability in writing/communication around the office, which may be why I was assigned to this project. Please share your advice or recommendation for resources to help me prepare and deal with this project. I'm looking for references to books/website/forums/whatever, to help me come up with the design of a plan with milestones, learn about best practices, task delegation, templates, buy-in, etc. I'm hoping specifically for resources targeting or giving special mention of introducing good documentation to existing, undocumented, projects. I would be very grateful for your responses. Ben

  Read the article

• 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

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