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
After every new program written a lot of paper documentation remains.
Apart from the usual scribble notes from the programmers there usually is a nice heap of papers containing physical model explanations, calculations and so on (equations, tables, graphs, little pictures describing variables ...)
We usually do numerically intensive calculations in console applications, which are not released to the public (remain in the house, only results go out). Before each project is finished all those papers have to be packed somehow with the application, so that one day, when someone will be reusing parts of it, has some idea what is what in there.
So far, we've been using the 'dirty' solution of just scanning all of it, and packing it up on the disc with the application.
So I was wondering ... for all science guys here in a similar situation ... how do you handle project documentation which is needed, but not released to the public ?
(the one that does, goes to the dtp laddies, and they make it nice and shiny - not our problem anymore :)
I use one of three options:
Keep everything in my lab notebooks, which I archive myself, for low-level stuff
Scan the paper document, and add to source control in pdf. It's ugly, but if someone needs it, it's there
Transcribe the equations, results, etc... in a clean format (usually Latex) for future reference, and again, add to source control. Official paper copy gets signed (I work in a highly regulated domain) and filed in a binder.
In the projects I've worked on we have done a lot of physics calculations in our programs and consequently we have a lot of whiteboard sessions with equations we are working on.
We keep a wiki for each major project and after each whiteboard session we physically photograph the whiteboard with a digital camera and upload/organize it within the wiki. We also scan in paper documents from developers notebooks if it is important and include it in the wiki as well.
Then, we back up the wiki on disc for storage. So our solution is pretty similar to yours, other than we use the project wiki for organization.
If it's important, it seems to me you should treat the internal documentation with the same care with which you treat the public docs.
I create UI paper prototypes when designing the UI of an application, which produces lots of A3-sized papers (in one project we had many desks covered with papers). When the design is ready or it needs to be mailed to somebody, I take pictures of it with a digital camera, so that I can produce a series of pictures showing how to perform some tasks on the UI, which serves as documentation of how the application is meant to work. This serves also as a backup, in case somebody steals/cleans away the original papers.
Here is some of the thoughts... Not so practical though :)
We can make it part of our Check-in notes. This may help the developers going to maintain the application.
Update the requirement document/Low level design document with these items
Related
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 need to document a MS-Access application that was created, developed and maintained completely by a power-user over 10 years.
This is an interesting situation because what they want is a manual so that a future developer can come in without prior domain knowledge and make changes to the frontend or the backend in a timely manner.
There are a few questions on my mind for this little project:
What is a good manual design creating application? Microsoft Word doesn't quite cut it.
What kind of things would you, the developer, need to know in order to make changes to things like forms, reports, tables or other Access objects?
Anything else I missed? Any pitfalls?
You could start with generating some automatic code documentation using MZ-Tools add-in for VBA. The same add-in can help you clean unused variable declarations, generate line numbers, reorder procedures within a module, etc.
Documenting forms is more difficult. My proposal would be to keep a screen shot, alltogether with a .txt file obtained through the undocumented application.saveAstext method.
In my experience, Access and VB6- based programs are plagued by more code replication and technical debt than programs in mainstream languages. I'm not sure why. Maybe it's the nature of Access as a "prototype" or "toy" database (though it can be quite powerful when yielded correctly).
If I had to choose between expending time on documentation and expending time on reducing technical debt, for example by remodularizing, eliminating repeated code, splitting long functions, etc., I would choose the latter. The improvement to maintainability and readability would be greater.
I know this is closed for long, but I can't refrain adding my 2 cents:
In the case mentionned, I think the most usefull doc to produce is a FUNCTIONAL documentation (which should have existed before starting the development in an ideal world).
Second is within the code itself, and that includes the VBA but also the field descriptions which can be set in Access and SQL Server.
Third is a (or a set of) nice database diagram.
Once you have that, all the rest can be generated by the new developer using HIS favorite tools.
Speaking about tools, I particularly like and recommend:
MZ Tools: specially to easily find which routines call the one your looking at
Smart Indent: to properly indent code. Trying to read badly indented code makes me sick
SqlSpec: (not free) generates HTML doc of the database itself for most database engines
Have you tried the using the built in database documenter? It will print out all tables, indexes, forms, controls, each property of controls. Code, the sql used and just about any thing else. This results in huge, but just massive printouts. However, while it will kill a few trees in the process it sure is a great way to impress the boss.
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 7 years ago.
Improve this question
My question is in regard to referencing open source frameworks. There are many of them for many different purposes. I personally leverage several of them in a single project. For example:
Unity
CAL/Prism
ValidationAspects
EnterpriseLibrary Logging
EnterpriseLibrary Exception Handling
EnterpriseLibrary Caching
Caliburn
All of these frameworks have helped greatly from a development effort perspective. There are however some negative aspects involved:
Tons of dlls (15 from the above list).
Application level (non-common assemblies and new assemblies) must reference many core dlls, which can be confusing) and tons of different namespaces are involved.
Deployment of said tons of dlls can get problematic (I sometimes use ILMerge to alleviate this and the above problems, but let's put that aside for now).
Open source project lifetime - open source projects come and go, so if any of these become no longer actively maintained, it can be concerning if there are internal bugs that need fixing or enhancements we want.
Obfuscation of "how to do things". We don't actively leverage every part of the above frameworks. In fact, several of these frameworks have overlap and provide redundant components and functionality. In terms of development, this can be confusing. We want a consistent implementation that is straightforward and easy to understand across our code base. Having multiple areas that do the same thing in different ways can be troublesome in this respect. This is probably one of my biggest concerns.
You're in big trouble if these frameworks reference different versions of other assemblies (ie. one internally references Unity 1.1 and another Unity 2.0).
The alternative? Include the source code in a common dll for your project(s) (ie. MyProject.Common). Let's put aside the issue of adherence to license requirements for the time being.
This has several negative implications too:
It's not as easy to leverage updates released by the framework's provider - you need to update your source code.
Encapsulation of functionality - it's easier to break this paradigm when the source code is all in your hands.
So, I know people probably have lots of opinions on this...and I'd like to hear them.
Thanks.
For some aspects of your problem, this might be relevant: http://en.wikipedia.org/wiki/DLL_hell#Running_Conflicting_DLLs_Simultaneously.
Another common solution to this problem is to write an encapsulation layer on top of the functionality needed, which at least protects your code from wild changes when upgrading to new versions of supporting libraries.
As to open source project lifetime, it should be clear which projects are healthy and which are not. For example, a project that is part of the Apache or Eclipse foundations are probably healthy, whereas some random thing on sourceforge is probably not. Generally, you can avoid this problem altogether by avoiding projects that do not seem active.
For the negatives to copying code into your project:
I know you wanted to put license aside, but you cannot in reality. I am not a lawyer and you should consult with one for your project if there may be issues, but if you are developing a proprietary system it could become GPL'ed accidentally.
It makes your development environment more cluttered. You have to worry about making sure the copied-in code ompiles properly, is being compiled with the right version, and has the right build scripts. You also have all this extra code in your IDE that takes up space.
As you pointed out, it makes updating code very difficult.
If you have to file bugs with the Open Source project, it becomes more difficult to do.
If you're not careful, a junior developer who doesn't know any better could go into the code and start mucking around with it.
There's probably more reasons not to do it, but that's a few. Hope that helps.
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
I have already built a site from scratch. It has banning, PM, comments, etc. The PMs and comments are done using markdown (like SO).
There are pros and cons for writing my own or using another software. But some cons keeping me from using another forum software is
Multiple Logins: One for the site, one for separate forums.
Need to Customization code: I'll need to change the toolbar in the forum software so I can access pages on the regular site.
Look consistency: It may look drastically different from my site even after applying lots of css changes.
Banning and User consistency. Users may be ban on site or on forums but not the other. users may select a different or multiple usernames on the forum instead of being forced to use the same username on both site and forum.
Should I write my own forum code or should I use something already written? What are some reasons for or against writing my own and using forum software?
The heuristic I tend to use is that if at least two or three of these are true, it's probably worth writing yourself:
It's one of your core business offerings.
You have the time, money and resource to specify, design, build, test and support it.
The amount of time you would need to spend evaluating, prototyping with, integrating and customising off-the-shelf packages is near to or greater than the amount of time you estimate that it would take you to build your own.
The off-the-shelf packages do not have good support. By 'good support' I mean that you can raise an issue, and be assured that somebody will look into your specific issue and provide a fix if it is found to be a bug.
None of the off-the-shelf packages meet your quality bar for security, performance, quality, etc.
You are not writing open-source software, and the off-the-shelf packages have a viral open-source license; be particularly wary of AGPL and other similar licenses.
One of the oft-quoted articles about this is from Joel Spolsky. Lately he seems to have just been writing flame-bait, but this was one of his worthwhile early posts.
Note that you can also take a combination approach, and use some pre-built things such as recaptcha and gravatar even from within a bespoke solution.
Writing your own forum software is nowadays in almost no case useful. The available software is highly customizable. For example, you can create your own skin to fit with the layout of your website. You can integrate the login with that of your website.
Writing your own forum is so complicated that the quality of your own software will be much lower than of something like phpBB or vBulletin. And dont forget the security bugs, the mentioned software has been reviewed by a huge amount of people. Until you reach the same quality (functionality, stability, security, etc), your website will be outdated and your forum software with it.
Once again, the current forum software is so adaptable and extensible, that it doesnt make sense to make your own.
I think it highly depends on your needs for the forum.
First off, is the forum itself an essential part of your website's function? Or is it more of a 'support' style forum?
If it's essential to your daily business, then it makes more sense to write your own - or at least highly customize an existing package.
If what you need instead, however, is a vehicle for customer support, or some sort of generic community revolving around your site, I might recommend looking at a completely different vehicle: something like http://getsatisfaction.com, or a Google Group, or some such.
(I'm in no way affiliated with either of those sites).
Regardless of the solution you choose, I'd recommend you give some serious thought to how essential the forum is. If it's not, then I wouldn't waste too much time configuring/setting one up. Instead, focus on what your site's main draw is, and spend the bulk of your time on improving that. You and your userbase will be much happier with that, IMO.
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 8 years ago.
Improve this question
I find myself wanting to develop certain projects, but most of the time I lack motivation because I develop by myself.
What I usually do is look for similar existing projects, and ask the developers if they like to collaborate, but it's rather hard.
Is there a good place (a website maybe) to find people that are interested in the same project as me, and therefore would like to collaborate?
You code by yourself?
Release the code on one of the open-source foundries. (code.google.com. sf.net. bitbucket.org , github.com ,etc...)
Pick an easy license (x11/MIT is good, GPL2/3/AGPL3 if you like, among others.)
Write simple instructions on how to deploy, run, with a one-page tutorial.
Have a website where you write about the stuff you build, and the stuff you'd like to build.
Find people who need some help and help them. Don't over-extend yourself.
It takes time to build trust. Trust takes time.
Update
You wrote:
What I usually do is look for similar existing projects, and ask the developers if they like to collaborate, but it's rather hard.
If you see an open-source project out there, odds are the developers already like to collaborate. What they might not want to do is talk about grand schemes about how to turn the software into the next fifty billion-dollar behemoth. Generally, if you join the mailing list, introduce yourself ("Hi, I'm Joe, and I like to do X, and I like this software."), get and use the software, and provide feedback and constructive criticism, and demonstrate that you are following instructions or at least attempting to, and then, then, if you provide a patch (or a branch if github) it might be looked at and considered.
Do follow the project methodology. For example, if they use tests, submit tests with your patch, that sort of thing.
I tried myself to start an open source project and failed. I had published my idea in a forum and there were about 10 or 15 people who wanted to join the project. Actually there were very little activity ...
I think the main reason for the failure was that I hadn't developed anything before going public. It would have been really useful to have at least a prototype. Another thing is defining a (simple) development process.
If I would try it again, I would:
develop a prototype
document the code and the architecture in detail
write down tasks others could do
describe the development process
design a nice website and promote my work
publish the code at google code or something like that
Check out the offerings at github.com. If you can use git, I often find some cool projects on there, and you can always fork the repository to help out.
First, you should register your project on an Open Source Forge. There is a comparison list on Wikipedia : http://en.wikipedia.org/wiki/Comparison_of_open_source_software_hosting_facilities
On certain forges, there is a way to ask for help. I know that SourceForge does: https://sourceforge.net/people/
I recommend that you read Karl Fogel's excellent and complete book on the subject : Producing Open Source Software. It is freely available online or in print from Amazon.
If you already have some code somewhere online, you could put an ad for your project on Stack Overflow's Open Source Advertising.
Quote from the link:
It must be an advertisement soliciting the participation and
contribution of programmers writing actual source code. This is not
intended as a general purpose ad for consumer products which just
happen to be open source. It's for finding programmers who will help
contribute code or other programmery things (documentation, code
review, bug fixes, etc.).
Openhatch
is the best place I have found to look for open source projects
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
In the course of your software development lifecycle, what essential design artifacts do you produce? What makes them essential to your practice?
The project I'm currently on has been in production for 8+ years. This web application has been actively enhanced and maintained over that time. While we have CMMI based policies and processes in place, with portions of our practice being well defined, the design phase has been largely overlooked. Best practices, anyone?
Having worked on a lot of waterfall projects in the past and a lot of adhoc and agile projects more recently, there's a number of design artifacts I like to create although I can't state enough that it really depends on the details of the project (methodology/team structure/timescale/tools etc).
For a generic, server-based 'enterprise application' I'd want the bare minimum to be something along these lines:
A detailed functional design document (aka spec). Generally something along the lines of Joel s' WhatsTimeIsIt example spec, although probably with some UML use-case diagrams.
A software techical design document. Not necessarily detailed for 100% system coverage but detailed in all the key areas and containing all the design decisions. Being a bit of an UML freak it'd be nice to see lots of pictures along the lines of package diagrams, component diagrams, key feature class diagrams, and probably some sequence diagrams thrown in for good measure.
An infrastructure design document. Probably with UML deployment diagram for the conceptual deisng and perhaps a network diagram for something more physical.
When I say document any of the above might be broken down into multiple documents, or perhaps stored on a wiki/some other tool.
As for their usefulness, my philosophy has always been that a development team should always be able to hand over an application to a support team without having to hand over their phone numbers. If the design artifacts don't clealry indicate what the application does, how it does it, and where it does it then you know the support team are going to give the app the same care and attention they would a rabid dog.
I should mention I'm not vindicating the practice of handing software over from a dev team to a support team once it's finished, which raises all manner of interesting issues, I'm just saying it should be possible if the management so desired.
Working code...and whiteboard drawings.
:P
Designs change so much during development and afterwards that most of my carefully crafted documents rot away in source control and become almost more of a hindrance than a help, once code is in production. I see design documents as necessary to good communication and to clarify your thinking while you develop something, but after that it takes a herculean effort to keep them properly maintained.
I do take pictures of whiteboards and save the JPEGs to source control. Those are some of my best design docs!
In our model (which is fairly specific to business process applications) the design artefacts include:
a domain data model, with comments on each entity and attribute
a properties file listing all the modify and create triggers on each entity, calculated attributes, validators and other business logic
a set of screen definitions (view model)
However do these really count as design artefacts? Our framework is such that these definitions are used to generate the actual code of the system, so maybe they go beyond design.
But the fact that they serve double duty is powerful because they are, by definition, up to date and synchronised with the code at all times.
This is not a design document, per se, but our unit tests serve the dual purpose of "describing" how the code they test is supposed to function. The nice part about this is that they never get out of date, since our unit tests must pass for our build to succeed.
I don't think anything can take the place of a good old fashioned design spec for the following reasons:
It serves as a means of communicating how you will build an application to others.
It lets you get ideas out of your head so you don't worry about tracking a million things at the same time.
If you have to pause a project and return to it later you're not starting your thought process over again.
I like to see various bits of info in a design spec:
General explanation of your approach to the challenge at hand
How will you monitor your application?
What are the security concerns and how are they addressed?
Flowcharts / sequence diagrams
Open issues
Known limitations
Unit tests, while a fantastic and arguably critical item to include in your application development, don't cover all of these topics.