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
Currently I'm wrapping up an application at the moment, and I'm at the stage where I need to document the application for anyone who wants to use it.
At this point, I just need something that will tell users how to use my program. Even though I tried to design it as user friendly as possible, I have a group of users who aren't tech savvy and need something they can refer to.
So my question is basically: What can I do to easily create help files?
This answer will pretty much assume you're using some version of Microsoft Visual Studio, although the first approach is generic enough to work on any OS with a HTML rendering engine.
You could create a series of HTML files, store them locally on the user's computer, and when the user calls up help, load those in the default browser (this being the same kind of approach Microsoft took with Visual Studio 2010). However, I think that's kind of a hacky solution.
There used to be a product called HelpStudio Lite; unfortunately it's been discontinued.
If you're willing to use Microsoft Help 2.0 (which was used through Visual Studio 2008 and some other products), you might want to take a look at http://www.mshelpwiki.com/wiki/tiki-index.php?page=Help2. Evidently it's some kind of wiki detailing how to put together your own Help 2.0 documents. I'm not sure if it will work with Visual Studio 2010 (this is because VS 2010 uses a new help system).
I really wish Microsoft would get their act together on the help documentation front.
EDIT: You may want to look at Sandcastle Help File Builder. I found it recommended at https://stackoverflow.com/questions/6023/what-are-good-tools-for-creating-compiled-html-help-files-chm... actually you may want to go read that thread as well.
Related
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 3 years ago.
Improve this question
This might sound a very vague question, but I am hoping to get some insight from all of you who can throw some ideas so that I can move in the right direction. I have ReadyAPI license and want to develop an automation framework around it. I can of course add assertions and create tests and everything within the tool, but I am wondering if there is a way I can build keyword or data driven framework around it so that I can have reusability, ease of use, adding assertions on the fly, execution via excel, or even adding assertions via excel (not sure). I am not sure if that's going to make creation of tests even more complex. Please provide your valuable inputs!
If you already have Ready API! then you probably don't need anything else. The licence is not cheap, so you'd have to consider if you really want to spend more money buying something from Mindtree. And, looking at their list of dependencies, there's always the danger of getting bogged down in the tooling and making them work together rather than doing actual work.
Why not start small and simple by doing some data-driven test cases using Excel or even a database as your source? I've used Excel to drive test cases and to populate assertions and not encountered any problems. For any customised behaviours, there's always Groovy to help. Then, once you've maxed out the capabilities of Ready API! look at something else.
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 found a great article here:
http://www.codeproject.com/Articles/18204/ASP-NET-controls-to-display-enum-values
where I studied it, learned a lot, and incorporated it as a new class library in my Visual Studio Solution.
Having borrowed the code and utilized in a web application, what is the best way to link up the original article on CodeProject to my Visual Studio solution (multiple projects) both so I can "bookmark" this article for later reference by me and my team member(s) and give credit to the original developer who came up with the idea. One idea I had would be an AboutBox in the EnumControls class library but the more I think about that it seems a bit stupid (I really only want some doc available at design time for my co-workers and for my future leaky brain).
How about a works cited page (text file in your solution) and then comments in code files where the code is actually used. This gives you and the other developers some immediate context of where it came from, but the solution level text file provides an artifact in your software process.
The VB.NET XML comment (''') would allow for IntelliSense documentation as well, which may be overkill, but it would be available to developers at code implementation time.
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 7 years ago.
Improve this question
Can anyone give advice, or point to any guides, on how to manage a community of open source software developers in writing api documentation?
A typical, unmanaged, starting point for most projects is to have a project wiki where anyone can freely create pages, add content to existing pages, edit existing content etc. The problem is that, despite people's best intentions, the wiki can easily end up being a disorganised, poorly written, incomplete, written in disparate voices etc etc.
So, what to do to improve the quality of the documentation?
I suspect a key ingredient is clear editorial/style guidelines, something similar to http://en.wikipedia.org/wiki/Wikipedia:Encyclopedic_style#Information_style_and_tone. Can anyone point to an example of such a guide tailored specifically to software apis?
Are there any other practices that people have found useful? E.g. form a core team of editors and accept that most documentation that gets added by the community will most likely need to be 'strongly edited'?
The short answer, that the solution is social/human and not technical. The way to get good documentation for any project is to have someone with time, in charge of doing high level organization for the documentation, and then being involved in the development and user communities to ensure that the documentation remains up to date and continues to address the problems and confusions that users typically have.
Community projects have accepted that you need point people (i.e. "managers," for aspects of the project like "translation," and "release," and for various components. The same thing needs to happen for documentation.
As for tools, Sphinx is really great though it's not "wiki like," exactly you can use whatever version control system your project is comfortable with to store documentation and configure your web server to rebuild the documentation following commits/updates/pushes. Which has always worked just fine for any project I've worked on/with.
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 7 years ago.
Improve this question
First and foremost, I would like to say I am very, /very/ new to programming and the like. If I decide to build this, this would probably be my first "large" project i've ever done myself.
What I am looking to build is a very simple Chat/IM client to use for the users in our office network. It would just call us their Windows logon name and use that to IM and the like. I'm talking a very simple client, with a list of names of people who are logged into the network, and option to IM them and an option to do a multiple user chat. It doesn't have to be visually stunning.
How difficult would this honestly be? Is it possible for me, someone who has very little knowledge when it comes to programming to teach myself how to build it?
If not, can you explain why this would be very difficult and what already built clients would work well for what I am using?
This is a big application. Your first parts will suck and refactoring it later will suck even more. I suggest building something small in the first place and then step from one bigger project to another.
XMPP/Jabber is IMHO the best solution for office IM. Most clients like Pidgin, Adium etc can connect to it. Every bigger company I worked for in the last years used it. Take a look at Openfire - A free open source XMPP server that you can directly connect on and which is easy to set up: http://www.igniterealtime.org/projects/openfire/
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 am going to be taking over from a developer here at work soon. Hence, I'll be supporting all the applications that he has written over the last few years.
My question is, when supporting an application that you probably don't know much about, what kind of documentation is most helpful to get a handle on how to fix problems, extend functionality, modify functionality, etc? I'm thinking it would need to give you an overview of what the software does, what interfaces it has to other software, what databases it uses, usernames, passwords, and so on.
Is there such a thing as a software support document? Referrals to any templates would be most helpful.
BTW, unfortunately, there are no requirements documents, specs, etc! So, really my question is, if my colleague had a day to write a single document for each application so that I could (more easily) support it, what would that document be and/or what would it look like?
I would ask for primarily some sort of flow chart/schema of the way the app functions.
I would want to be able to know how each file interacts with other files (and the database). So this way, you'd know where to start to fix a bug or add a new feature, etc.
So to do a quick, text mockup of it:
Index.php -> Login.php -> Dashboard.php
Index.php:
Has login box. Submits login into to login.php
Login.php:
Verifies data with database entries, shows error on fail or sends to Dashboard.php
Dashboard.php:
Once logged in this acts as a main menu
Something along these lines? For basic documentation I'd think this is the way to go.
Hope this helps. Good luck!