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 9 years ago.
Improve this question
I'm responsible of finding a good way to document the software project I'm working on.
What things are important to document? Should documentation of code and design mainly be in the code in the form of comments? Should we put text files or Word documents directly in the source control togetether with code? Should we use a wiki?
Factors to think about include how easy it is for the current team to create the documentation, and how easy it is for other developers to find, correct and extend the documentation later. My experience from many projects is that developers tend to not write documentation because the system for writing it is too complex or developer unfriendly, and that after a few years, new developers can hardly find the little documentation that was written.
I'm interested in what approaches you have used in similar projects. What worked well, what did not work well, and why?
Some key facts about the project:
The platform is C# and .NET.
We use Visual Studio and Team Foundation Server for source control and work item (task) management.
We use Scrum and test-driven development and are inspired by domain-driven design.
The software consists of a collection of web services and two GUI clients.
Other clients are going to integrate with the web services in the future. The integration will be done by other developers on other teams (so the web services form a kind of API).
SharePoint is heavily used throughout the development environment. Most projects have a SharePoint site, including ours.
On our project's SharePoint site we currently have a bunch of MS Office documents on things like requirements, design, presentations for stakeholders etc. Keeping everything up to date is hard.
We also have a SharePoint wiki for the development team only, where we document things in an unstructured manner as we go along. Examples include how our build scripts are organized, our testing policy, coding guidelines.
The software is an in-house application in a fairly big financial institution.
The software is developed by a team of six people over a period of ~1 year.
The developers are consultants hired in for this project only, and will not be available to help in the future (unless the client decides to pay for it).
The client has few guidlines for how this kind of project should be documented.
I think the most important things to document are the decisions. This goes for everything from requirements to architectural choices. What are the requirements of module X? How are these requirements represented in the architecture? Why did you choose architectural pattern A over B? What are the benefits? The same goes for source code: it is common knowledge that commenting the why is way better than the how.
How you document these decisions does not matter that much in my opinion, whether you use a Wiki or a Requirements document made in Word. More important is that these documents are always up-to-date and that it is easy for anyone to access them. This can be achieved by using a wiki, or placing the documents under source control, as you say. If only a few have access to them, they are more likely not to get updated, and not to be read when necessary.
We use a Wiki for our current project and it works very well. It is easy to access for anyone (developers, managers, and customers) and a history can track changes, so you know what has been changed and why. Furthermore, we try to document the code in a meaningful way and document the major design decisions. We try not to document too much, e.g. minor things, as it is always hard to keep those things up-to-date and it is not worth the effort, imho.
Worst for me than lack of documentation is excess of documentation.
Keep in mind that yes: it's really important to document your project, but also that the major part of your documentation is always at risk of never been read at all.
So, I think that a good starting point consist in thinking of your documentation more like something that you may use to introduce new developers to your project than an over detailed description of the inner workings of your software.
G'day,
Definitely use a wiki. I'd recommend TWiki as it's an excellent and extensive implementation of a wiki without being too complicated to install and manage.
Here's a couple of initial thoughts.
Categories:
Start off with an initial ontology of what you want to capture but
allow people to add new categories or sub-categories as required,
allow people to retitle (sub-)categories as required and maybe as agreed for this one so you don't get fragmentation for multiple names for basically the same thing.
let any initial (sub-)categories wither and die if they are left empty. Do this at the end of the project as some areas may only have entries towards the end of a project.
Tagging:
Start using a tag cloud. BTW here's an excellent plug-in available for TWiki to start classifying content early on in the project. Retrofitting tags is almost impossible to do. Starting tagging early also allows people to search for information that may be there already rather than having the same info located in multiple places.
HTH I'll come back and add more points as I think of them.
First and most important, have the comments written in such a way that NDoc can parse them. This is the best way to have the code itself documented, as the developers have to change their development practices very little, and you can generate pages that explain the code without having to look at the code.
Second, getting developers to write documentation is not easy, and getting them to do it might be an exercise in futility. This is where products like Fogbugz come into play. They will help manage the development with tickets, help track check ins, and when your done an iteration, generate release notes.
In conclusion, your best bet is to find the most effective solution that fits in with the devs existing process. If it impacts their development process very little, they will be more likely to adopt the system.
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 2 years ago.
Improve this question
I work on developer tools for a particular product. There is a competing set of tools for the same product produced by a different company. The user-base is split roughly 50-50 between us.
Recently, the other company has introduced scripting to make their own tools extensible by end-users. This is a feature that we have had planned for our tools for a while, but it is only now that we are able to start implementing it.
My question is: should we try as much as possible to collaborate with the developers of competing product so that end-user scripts can be shared between users on the different products? We would obviously require different implementations, but share the same syntax. This would obviously be better for the community as a whole since there would be more interoperability.
The downside of collaborating like this is that the competing product's scripting language is slightly tailored towards their own implementation. We would have to jump through a few hoops to create an implementation for their scripts on our platform. Or, we would have to somehow convince our competitor to modify their scripts so that they are platform agnostic.
So, to rephrase my question: should we try to collaborate, thus making our community happier, or should we produce a competing scripting language that is more appropriate for our platform?
I realize that this is a very general question with no single right or wrong answer. What I am looking for is a good explanation of the pros and cons of each approach.
I would write something that is specifically tailored towards my own system (don't compromise your technical quality) and then release and fully support a compatibility layer that allows my competitors scripts to run on my system (make it easy for users to migrate).
I'd stay away from doing things that will try to lock people in and cripple them if they move. These tactics worked once upon a time but in this day and age don't really cut it any more. I'd even go so far as to actually (unofficially on fora etc.) help people who are having trouble porting scripts running on my system to my competitors.
Another way to ask the question (and to answer) is to wonder WHAT KIND of script language is DESIRABLE FOR USERS.
If your competitor went a lock-in route with a proprietary scripted language, then please your users (and get a competitive edge) by using a STANDARD scripted language.
Doing so will immensely increase the value of your tool as many persons ALREADY know the scripted language.
Nobody wants to learn a new language.
Would building a unified scripting language harm your customer-base or give the competitor the competitive edge?
Obviously if you want to lock in customers, go solo which will prevent your customers from easily switching over to the competitor's product (sounds a little like Microsoft tactics) or if you know your product is superior, a collaboration will allow you to get customers from the competitor in which case customers will have the choice to choose which business model suits their needs, make a choice based on the quality of the product as a whole as well as which features they really need instead of being locked into an invisible contract due to the choice they made initially.
Going the collaboration route will also put your company in a position where developers will respect your company (for not being a greedy monopoly monster) instead of boycotting it due to their "moral" beliefs in open standards.
I would say that if possible make it compatible, not so much to cooperate but to compete. Making an incompatible solution would lock you customers in to some degree (you don't have any yet with a lot of scripts - so not much gain), but making a compatible solution keeps the door open for customers of your competition to migrate (they might have some scripts by the time you ship yours).
Just my 2cents
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
In short I'm creating a 2D mmorpg and unlike my last "mmo" I started developing I want to make sure that this one will scale well and work well when I want to add new in-game features or modify existing ones.
With my last attempt with an avatar chat within the first few thousand lines of code and just getting basic features added into the game I seen my code quality lowering and my ability to add new features or modify old ones was getting lower too as I added more features in. It turned into one big mess that some how ran, lol.
This time I really need to buckle down and find a design that will allow me to create a game framework that will be easy to add and remove features (aka things like playing mini-games within my world or a mail system or buddy list or a new public area with interactive items).
I'm thinking that maybe a component based approach MIGHT be what I'm looking for but I'm really not sure. I have read documents on mmorpg design and 2d game engine architecture but nothing really explained a way of designing a game framework that will basically let me "plug-in" new features into the main game.
Hope someone understands what I mean, any help is appreciated.
If you search for component-based systems within games, you will find something quite different to what you are actually asking for. And how best to do this is far from agreed upon just yet, anyway. So I wouldn't recommend doing that. What you're really talking about is not really anything specific to games, never mind MMOs. It's just the ability to write maintainable code which allows for extension and improvements, which was a problem for business software long before games-as-a-service became so popular and important.
I'd say that addressing this problem comes primarily from two things. Firstly, you need a good specification and a resulting design that makes an attempt to understand future requirements, so that the systems you write now are more easily extended when you come to that. No plug-in architecture can work well without a good idea of what exactly you hope to be plugging in. I'm not saying you need to draw up a 100-page design doc, but at the very least you should be brainstorming your ideas and plans and looking for common ground there, so that when you're coding feature A, you are writing it with Future feature B in mind.
Secondly, you need good software engineering principles which mean that your code is easy to work with and use. eg. Read up on the SOLID principles, and take some time to understand why these 5 ideas are useful. Code that follows those rules is a lot easier to twist to whatever future needs you have.
There is a third way to improve your code, but which isn't going to help you just yet: experience. Your code gets better the more you write and the more you learn about coding. It's possible (well, likely) that with an MMO you are biting off a lot more than you can chew. Even teams of qualified professionals end up with unmaintainable messes of code when attempting projects of that magnitude, so it's no surprise that you would, too. But they have messes of code that they managed to see to completion, and often that's what it's about, not about stopping and redesigning whenever the going gets tough.
Yes, I got what you want...
Basically, you will have to use classic OOP design, the same one that business software coders use...
You will first have to lay out the basic engine, that engine should have a "module loader" or a common OOP-style interface, then you either code modules to be loaded (like, as .dlls) or you code directly within your source code, using that mentioned OOP-style interface, and NEVER, EVER allow a module to depend on each other...
The communication, even inside your code, should be ALWAYS using a interface, never put "public" vars in your modules and use it somewhere else, otherwise you will end with a awfull and messy code.
But if you do it properly, you can do some really cool stuff (I for example, changed the entire game library (API that access video, mouse, keyboard, audio...) of my game, in the middle of development... I just needed to recode one file, that was the one that made the interface between logic, and game library...)
What you're thinking about is exactly what this article describes. It's a lovely way to build games as I have blogged about, and the article is an excellent resource to get your started.
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 2 years ago.
Improve this question
I try to be very cautious with this question. There are at least three different web-development frameworks available in Smalltalk. The most prominent seems to be Seaside but there is also AIDA/Web and Iliad.
They seem to be very similiar, but this impresson may be wrong. I wonder who has tried the different tools and can share the pros/cons of the different packages.
A more concrete question would be, do yo know of let's say any software in the bookkeeing area which has choosen to use either of the three (or other) web development frameworks.
Here's one other question. What about maturity and compatiblity. Which framework can one judge as the "most" stable?
99% of my practical experience is with Iliad, so my comparison is primarily about how I got to choose Iliad instead of the others.
Seaside. Tried it first, it is the most known and the first you stumble in. I found it hard to understand (as always, no matter what you use, when it gets to real implementation you always run into issues that fit badly with the general theory), there was little documentation around and the community seemed to care little about telling n00bs how to grow up. I eventually dropped it to check Aida. You find them here: http://seaside.st/ and on IRC at #seaside
Aida. I really liked it, as Janko is extremely patient and supportive. It is large, though. I decided to use it, when I was to start implementation for our project and it was only by chance that I ran into Iliad a few days before starting. You find Aida here: http://www.aidaweb.si/ and on IRC at #Aida
Iliad. The main reason I chose it was that I had just dropped Squeak and switched to gnu-smalltalk. gst seemed to have a lot of ongoing activity on Iliad, so I reckoned I was probably going to get a better assistance with it. It is much smaller as a concept (though it does absolutely everything) and I had very little trouble in getting started and in tweaking it to what I needed for. It also proved to be well managed, as I went thru 3 releases without ever being in trouble with what I had already deployed. You get answers to questions usually in 12-24 hours max, which is fine for me. You find Iliad here: http://www.iliadproject.org/index on IRC issues are usually channeled on the #gnu-smalltalk channel
What we are doing is a GUI for a PostgreSQL database used to manage a large multimedia dictionary, that in turn produces content (among others, for KDE-edu). I have no notion of booking apps in general, so I cannot answer to your question properly.
Yet, speaking as an analyst, a booking app is mostly a DB with an online GUI, so I see no reason why you could not make it. Much will depend on how easily your db can translate into objects. You could use a RDBMS, as we did, and design tables to map objects, or use an OODBMS. Both solutions have pluses and minuses, none of them is going to have an impact on your choice of framework, I'd say.
My suggestion is that you take a month or so in making experiments and see what better fits you. I don't think there is a tool that fits everyone, we are all different and what is easy for me may be hell for someone else (and the other way round, obviously). So try your car before buying it ;)
I would not invest too much time in studying the general theory. Using a smalltalk framework is going to turn upside down the way you make a web app anyway, and your first contact is going to be full of "false friends" you inherit from previous mindsets. Your best asset is definitely going to be "how quick can I grasp what they tell me", and this is largely an individual thing, depending on you and on who you bump into. So I'd really suggest you get your hands dirty BEFORE reading too much theoretical stuff.
These frameworks are all quite different and have different goals. It would be interesting to collaboratively create some kind of comparison.
As an author of Seaside I can provide the key properties of Seaside only:
Seaside makes building web applications feel like composing traditional GUIs: components can be freely composed and reused. Sequences of components are defined using a sequence of Smalltalk statements.
Seaside has a layered architecture, providing you with high-level abstractions (components, control flow, callbacks, HTML generation, JavaScript generation, ...) over low-level concepts (HTTP, Request, Response, URLs, HTML, JavaScript). If you need to, Seaside gives you full access to low-level constructs too.
There are two Seaside books to help you get started: Dynamic Web Development with Seaside and Seaside Tutorial.
Seaside provides a tight integration into various state of the art web technologies: JavaScript (JQuery and JQueryUI), SVG, RSS, HTML5, Comet (Server-Push)
Seaside runs identically on most today's Smalltalk platforms: Pharo Smalltalk, Squeak, GNU Smalltalk, GemStone Smalltalk, VW Smalltalk, VA Smalltalk, and Dolphin Smalltalk. It is supported by all vendors of Smalltalk platforms.
Seaside provides industry proven open-source components for meta-modeling (Magritte) and content management (Pier).
Let me introduce some strengths of Aida/Web too, because as its author it would be hard to me to compare with other two frameworks. Aida strengths are:
RESTfull URLs
MVC support, every domain object can
have its own RESTfull URL, each domain class has its own web presentation class,
Integrated AJAX and Comet
support, you don't see any difference
between a traditional and Ajax
programming anymore,
Tree-like control flow for GUI-like
control flows, without need for
continuations
Building web pages programatically by
composing from components/elements
(no template based)
Scalable in complexity and performance
Integrated security with access
control and users/groups management
Ported to most Smalltalk dialects:
Squeak/Pharo, VisualWorks, Gemstone
GLASS, Dolphin, Smalltalk/X
Prime and most fresh example of Aida at work is this year Smalltalk Google Summer of
Code site.
This is the is a nice example because it was developed it in maybe a week in
total, together with a development of GSoC process in parallel and in
the same time managing that process as an admin. This site is actually
an extended Aida/Scribo CMS, with strong use of so called scriblets,
that is, dynamic web "includes" directly into the content of the site.
That way I was able to very quickly support the new ideas which come
during the evolving GSoC process.
Well, Suixo uses Seaside. Take a look at the GSoC projects we defined. Its more ERP than bookkeeping, and currently focused on healthcare.
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 6 years ago.
Improve this question
Is there any website specifically for sharing and accessing actual software development processes implemented in software organizations?
There are lots of resources that give advices and descriptions for implementing these processes. They are very useful. But I think having actual example process definitions would be very useful as well. Specifically, I am now looking for an example process definition in CMMI. I overviewed several books but none of them presents any specific example implementation.
I think the authors are probably concerned that the readers might just copy these process definitions without understanding specific customization decisions in them. They are very rightful in this concern. But anyway, I think this is an important need for general software community. Understanding and interpreting an example document properly should be the responsibility of the reader.
If you don't know any good resource that shares specific implementations of the processes, what do you think about this need? Don't you think that we, software engineers and developers, should share our process definitions as we share our code?
There is a good wikipedia article with a lot of resources. Also searching for "UCM Workflows" on IBM Rational web would lead to good examples, I'd rather not deep link into their page. The question is how far into detail you want to go into the process. Most resources available will only give you a rough overview of basic development processes.
What you mean by examples is probably going into the details of specific implementation of such development process. For larger and established software development companies their development process will most likely not be readily reusable, because it will involve many custom made tools and configurations and the process itself could be in some cases considered proprietary, giving the company a competitive edge over others. Going into details about the process could also pose a security risk, because it would reveal a lot about the company infrastructure. So I don't think you would find much in form of examples from successful software development companies and what you find is either too general or written by theory-crafters.
This is a field of special interest for me for almost a decade now and I only ever found bits and pieces published about specific processes used by major software corporations. I would certainly welcome a forum to share experience with other professionals in this field.
Try looking at EPFC - Eclipse Process Composing Framework, there are some example processes, tools and best practices to develop them.
There are merits in providing some sample templates which would assist someone getting started. The limitation is that it could force the user to adopt the templates without thinking about the application.
Most methodologies adopt a 'guideline' approach with some tailoring. For example, the RUP system, promoted by Rational (now IBM) traditionally suffered from the assumption that it was only applicable to large scale projects. This prompted discussion on how RUP can be applied to a one person project. Of course it takes work and effort and if you are a small project team sometimes tailoring the methodology could overshadow the project; i.e are you trying to build a methodology or a product ?
As for samples some examples are:
Agile Unified Process - gives good examples of both process, artifacts and also commentary on the process and it's application,
Open Unified Process - again samples, artifacts and easily navigated system.
I do not know of such a "process repository". I only see general description like this one.
Note: While the CMMI implementations I have come across are quite tailored for a specific enterprise/environment, I found them truly effective when evaluated/challenged.
In that regard, the study Six Sigma and CMMI interesting, not so much as a practical example of CMM, but rather as a way to put CMM in perspective.
The OPEN Process Framework Repository Organization's web site contains an online repository with over 1,100 method components.
It doesn't contain final methods because, according to method engineering precepts, you must compose your methods from these components depending on your product, project and organisational needs.
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
What would you suggest for the following scenario:
A dozen of developers need to build and design a complex system. This design needs to be documented for future developers and the design decisions must be noted. These reports need to be made about every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about the things they helped design and integrate and then one person combines each of these documents together. The final document will probably be incoherent or redundant at times since the person tasked of assembling everything won't have much time to adjust every part.
Assume that the documentation parts from each developer arrive just a few days before deadline. A collaborative system (i.e. wiki) wouldn’t work properly since there wouldn’t be anything to read until a few days before deadline.
Or should a few people (2-3) be tasked with writing the documentation while the rest of the team works on actually developing the system? The developers would need a way to transfer their design choices and conclusions to the technical writers. How could this be done efficiently?
We approach this from 2 sides, using a RUP style approach. In the first case, you'll have a domain expert who is responsible for roughing out the design of what you're going to deliver - with developers chipping in as necessary. In the second case, we use a technical author - they document the application, so they should have a good idea of how it hangs together, and you involve them right through the design and development process. In this case, they can help to polish the design, and to make sure that it matches what they thought was being developed.
We use confluence (atlassian's wiki-like-thing) and document all kinds of different "things". The developers do it continiously, and we push each other for docs - we let peer pressure decide what is necessary. Whenever someone new comes along he/she is tasked with reading through everything and to find out what still is correct. The incorrect stuff is either deleted or updated as a consequence of this. We're happy when we can delete stuff ;)
The nice thing about this process is that the relevant stuff stays and the irrelevant stuff is deleted. We always "got away" from the more formalized demands by claiming that we could always construct the word documents they wanted if "they" needed them. "They" never needed them.
I think alternative 2 is the less agile, because it means a new stage to the project (although it may be in parallel with tests).
If you are in an agile model, then just add documentation (following a guideline) as a story.
If you are in a staged approach, then I would nevertheless ask developers to work on documentation, following some guidelines, and review that documentation along the design and the code. Eventually, you may have a technical writer reviewing everything for proper English, but that would be a kind of "release" activity.
I think you can use Sand Castle to document your project.
Check it out
Sand Castle from Microsoft
It's not a complete documentation, but making sure that interfaces etc. are commented using Doxygen-style comments means writing code and documenting it are closer together.
That way, developers should document what they do. I still think a review by the architect(s) is needed to ensure consistent quality, but ensuring people document what they do is the best way to ensure they follow the architecture.