Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
In which document would a file specification belong? Perhaps this file is used as an input to a third-party system. Would it belong in its own document? Or would it be better to put it in the functional or design spec? Or somewhere else?
When I say file specification, I mean a description of what format the file is (CSV, fixed width, etc), columns, data types, etc.
Also, where should you document how the file is generated? i.e. business rules/algorithms which are used to generate the file.
I always document file formats and layouts in the design spec. Unless it is a simple file I document the layout in an Excel document embedded in the design spec.
Regarding your second question, the rule of thumb is the functional spec documents the "what" and the technical/design spec documents the "how". Business rules, triggering events, and algoritms should be documented in the functional spec. How your program implements those rules is documented in the technical design spec.
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
This question does not appear to be about a specific programming problem, a software algorithm, or software tools primarily used by programmers. If you believe the question would be on-topic on another Stack Exchange site, you can leave a comment to explain where the question may be able to be answered.
Closed 8 years ago.
Improve this question
We used Adobe inDesign to design story books. We need both the PDF file as well as epub file. Since we all view in PDF during the process, the final clear product in PDF, when we export as epub file, it's huge. It all messed up the original design. What can we do?
Why did it happen?
I've worked on ONE project going from InDesign to ePub about two years ago - and you are right it is a mess. It didn't understand which local overrides to keep and practically every paragraph had style="localoverride1 localoverride2 substyle3 etc" in it. It was a mess to sort and clean up.
After that miserable experience we've found that it is better to view PDF and ePub as two separate products. Our workflow takes source XML and goes EITHER into InDesign OR through an XSLT to make an ePub. We no longer use InDesign to attempt to make ePubs - with an XSLT there is a LOT more control over the look and feel of the final product.
However if you are dead set on using InDesign - I've heard that it does fixed layout "epub" fairly well (basically it ends up being a bunch of images - it's not reflowable).
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I've use javadoc, as well as a variety of different XML based doc-generation systems. Javadoc is fine, XML based doc-generators are hideous, with the XML getting all over the comments and turning the comments into soup.
I've looked at markdown, and the fact that it is easily parseable into structured data but also super human-readable would make it perfect for in-code comments, where the readability of both the docs and the plaintext is of utmost importance.
Are there any markdown based doc-generators out there already? Is there any reason why it wouldn't work which I don't know of?
There exits some Markdown-Doclets (f.ex. http://www.richardnichols.net/open-source/markdown-doclet/ ) which can be used with JavaDoc.
Maybe you are also interested in the famous doxygen tool. It doesn't use Markdown but the format is very similar to it (f. ex. unordered lists with - etc.).
You may try mdoc to generate Markdown based documentation. It reads all the .md files and produces HTML based documentation. It also creates a TOC. Check it out.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'd like to write an architecture document for a little ruby project I'm working on, and being an architecture document it'll benefit from a few box and stick diagrams.
What's the done thing on open source projects for this situation? Should I be practicing my ASCII art, or should I include PDFs or something in my doc folder?
Note that this is a stand-alone document, not API documentation generated from the code.
Check out umlet-github, a Google Chrome extension that allows you to create diagrams in UMLet, store them as UXF files in your repository and view them in your browser within the GitHub interface.
I would say use Gliffy, where you can export diagrams to .JPG or .PDF and attach them to your README.md file.
You can also get a sharable link and include it in there. Very handy.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
Неllо. I develop system that works with stock exchange(system, below). And there is a lot of information my program need to interact with this system. This system has formal declared interface, but different details beside this declaration and requirements to my system is often changed. So how can I organize available information about this system and requirements to my program that it could be both easy to understand and easy to change.
Your first and foremost goal is to create documentation for the relevant APIs your program exposes and then add documentation for the configuration files, maybe even set up a validator for configuration that.
Automatically generated content from code annotations (depending on your solution, it might be .NET's XML docs or PHPdoc, etc.) is the first step – this will help you document classes and interfaces as you work on the code. The next step is documenting non-code assets. If you have XML configuration, you can write schemas to validate against, for example.
After that comes integration documentation – steps that need to be taken on the production server and/or workstations to install, upgrade and maintain the application, including support scripts.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
I have various documents some are large some are small, we have to draw up some form of model that would describe how a user interacts with each document when following them for a build. For example, a user might.
Follow Document 1 to Section 10 then be pointed to Document 2 to complete then return back to Section 10 in document 1 etc.
Has anyone ever drawn up some sort of chart to demonstrate this kind of thing for documentation, it is fairly standard for systems but i have never done it regarding documentation and I am just wondering if there is a formal method of doing this for documentation and is there any examples or standard guides to follow.
I think I would use an Activity diagram with Swimlanes for each document.
An alternative would be an IDEF0 diagram(may be appropriate if there are instructions for completing each document, and/or different roles for different steps)