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.
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
Currently I am working on porting a benchmark application to another system. I am working alone, so I am frustrated about which software methodology I really have to use. Please give me some ideas.
I am going to assume you're wondering which Agile approach to use on your project as you tagged your question accordingly.
Agile is mainly about:
Delivering working software continuously and regularly
Aiming at technical excellence and avoiding technical debt
Improving the way we work and retrospecting regularly
I'd say whatever you use, even your very own approach to software development, if you can check those three items from the list, then you're pretty much Agile to me. Some people need strict guidelines and artifacts and that's fine, they help people become Agile but are far from being mandatory despite the dogmas out there.
Here's how I would approach your situation.
Take a step back and try to identify the most important features or abilities of this benchmarking application. By most important, I mean those features that the people using it in the end cannot live without. Once you have a list of those, put them on post-it notes, index cards, trello, jira or whatever tool you want to use.
Split each of those features into full-stack chunks of functionality that are business driven. I'm not talking about technical tasks here, but smaller features usable by actual people. I usually opt for the "Grandma Driven" approach here, asking myself "would grandma be able to understand what I'm trying to do?". It's just to make sure I'm focusing on a full stack feature and not a technical task like "populate database". One way to see this is also by applying dimensional planning to each of the features you identified (http://www.xpday.net/Xpday2007/session/DimensionalPlanning.html).
Set yourself an iteration length (I usually go for 1 or max 2 weeks when I'm working alone) and get to work one small item at a time. Don't write code for later, only what you need to solve the problem at hand. Quality is not an option. Focus on good coding and testing practices.
At the end of your iteration, check how many features you implemented and put that number somewhere on a chart, in a google spreadsheet or whatever. This will help you see if you're on track. Get feedback from colleagues or any potential users of the system and reflect on that feedback. It's not because you're porting to another platform that you can't make it better.
If you end up not having small enough granularity with what's left or not enough stuff in your list of things to do, spend some time repeating steps 1 to 3.
At the end of each iteration, keep tracking how many items you did just to see if you still have a good enough pace. If not, ask yourself why and change something in the way you work or get help. Again, your main focus is to make progress and deliver software that works at the end of each iteration.
It might not answer your question and I know I didn't give you an answer of the type, use kanban, scrum or whatever but I truly believe it's not appropriate in your specific case and would only generate overhead and boredom for you.
Hope that helps anyway, good luck with your project.
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 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.
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 3 years ago.
Improve this question
We have a project hand over from on shore team to our team (off shore) not long ago. However we were having difficulties for the hand-over process.
We couldn't think of any questions to ask during their design walk-through, because we were overwhelmed by the sheer amount of information. We wanted to ask, but we didn't know what to ask. Since they got no question from us, the management think that the hand-over process was been done successfully.
We had tried to go through all the documentation from our company wiki page before attending the handover presentation, but there are too many documents, we don't even know where to start with.
I wonder, are there any rules or best practices that we can follow, to ensure a successful project hand-over, either from us, or to us.
Thanks.
In terms of reading the documentation, personally I'd go for this order:
Get a short overview of the basic function of the application - what is it meant to achieve. The business case is probably the best document which will already exist.
Then the functional specification. At this point you're not trying to understand any sort of how or technology, just what the app is meant to do. If it's massive, ask them what they key business processes are and focus on those.
Then the high level technical overview. This should include an architecture diagram, required platforms, versions, config and so on. List any questions you have.
Then skim any other useful looking technical documents - certainly a FAQ if there is one, test scripts can be good too as they outline detailed "how to" type scenarios. Maybe it's just me but I find reading technical documents before I've seen the system a waste - it's too academic and they're normally shockingly written. It's certainly an area I'd limit the time I spent on if I didn't feel I was getting a reasonable return for the time I was spending.
If there are several of you arrage structured reviews between you and discuss the documents you've read, making sure you've got what you need to out of it. If the system is big then each take an area and present to the others on it - give yourselves a reason to learn as much as possible and knowing you're going to be quizzed is a good motivator. Make a list of questions where you don't understand something. Having structured reviews between you will focus your minds and make it more of an interactive task, rather than just trawling through page after page of tedious document.
Once you get face to face with them:
Start with a full system demo. Ask questions as they come up, don't let them fob you off with unclear answers - if they can't answer something have it written down and task them with getting the answer.
Now get the code checked out and running on your machines. Do this on at least two machines - one they lead, one you lead. Document the whole process - this is the most important step. If you can't get the code running you're screwed.
Go through the build process. Ensure that you can build the app (including any automated build and unit tests they may have). Note that all unit tests should pass - if they don't or if they say "oh, that one always fails" then they need to fix that before final acceptance.
Go through the install process. Do this at least twice, one they lead, once you lead. Make sure that it's documented.
Now come up with a set of common business functions carried out with the application. Use this to walk the code with them. The code base will be too big to cover the whole thing but make sure you cover a representative sample.
If there is a database or an API do a similar exercise. Come up with some standard data you might need to extract or some basic tasks you might need to carry out using the API and spend some time working through these with them.
Ask them if there's anything they think you should know.
Make sure that any questions you've written down anywhere else are answered.
You may consider it worth going through the bug list (open and closed) - start with the high priority ones and talk through anything particularly worrying looking. Even if they've fixed it it may point at a bit of code which is troublesome.
And finally if the opportunity exists - if there are any outstanding bugs or changes, see if you can pair program a couple.
Do not finally accept the app unless you are 100% sure you can:
Get the code to compile
Get the code to build (including the database)
Get the application installed
Do not accept handover is complete until they have:
Documented anything you picked up on that wasn't covered to your satisfaction
Answered ALL of your questions - a question they won't answer after being asked repeatedly screams of something they're hiding
And grab their e-mail addresses and phone numbers. Even if it's only informal they'll probably be willing to help out if the shit really hits the fan...
Good luck.
My basic process for receiving a handover would be:
Get a general overview of the app, document it
Get a list of all future work that the client expects
... all known issues
... any implementation specifics
As much up-to-date documentation they have
If possible, have them write some tests for critical components of the system (or at least get them thoroughly documented)
If there is too much documentation (possible) just confirm that it is all up to date, and make sure you find out from them where to start, if it is not clear.
Ask as many question as possible; anything that comes to mind, because you may not have the chance again.
Most handovers, perhaps all of them, will cause a lot of information to be lost. The only effective way to perform a handover that I have seen is to do it gradually. One way to do it is to allow a few key people from phase One to stay on the project well into Phase Two.
The extreme solution is to get rid of all handovers, and start using an Agile mindset.
As a start, define the exit criteria for the handover. This should be discussed, negotiated and agreed with both parties and make sure higher management knows this. Then write up a checklist of all things needed to achieve the exit criteria and chase it.
Check out "Software Requirements" and Software Requirement Patterns for ideas on questions to ask when gathering information about a project. I think that just as they would work for new development, they would also help you to come to terms with an existing project.
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
What do you do when you join a team that says they use Scrum, but only use it as a time-management tool and not the whole process?
How can I reinstate back testing and documentation?
I was thinking to start off with adding user stories specifically for testing and documenting.
Perhaps someone else has more experience with this then I do about this as I am sure its not that uncommon.
The key to scrum is that a task be identifiable as "done" before it can be classed as done. How does you company assess whether something is done without reviewing documentation and tests?
Perhaps they have an unusual, but valid, way of doing it. Or perhaps they have missed the point of "done tasks". I'd suggest you start by asking them how they measure down and whether it could be improved. Then suggest documentation and testing as the way of improving the process.
Note that neither testing nor documentation are in fact part of Scrum. Scrum is a pure project management approach - the required engineering practices, like the ones you mention, are supposed to "emerge" during the project. And most specifically, they are supposed to be identified during the heartbeat retrospectives that you do at the end of every sprint. Are you doing those? Can you bring up your concerns there - and are they actually the biggest concerns the team has?
Is the issue that they don't have any documentation and tests, or that they aren't implementing the entire Scrum methodology? Those are 2 very different problems in my mind.
I would much prefer an organization that has taken the time and effort to find and fit a development process that matches their development style as opposed to mandating down from on high the one true process. So I would not be concerned at all if they were using a process that they called Scrum but that didn't meet all the "official" guidelines. Try to determine why the process is the way it is. Chances are that if they have taken the time to tailor it, the team will be receptive to your ideas, especially if you have taken the time to determine why things are the way they are. If you simply approach it as "this isn't Scrum and so isn't right", you will probably not make much headway, but by being pragmatic about the benefits you can likely make some substantial improvements.
Alternatively, if they aren't doing testing and don't have any documentation I would consider that a fairly bad sign. And by documentation I am taking the minimalist view here - a list of features, bug tracking, etc. - I would be very concerned by the absence of these items, less concerned by the absence of items higher up the abstraction list. In the absence of support from management, I would suggest you lead by example. Take it on yourself to setup a simple bug tracking system (there are several - in a pinch, simple text lists in a central location work as well). Don't declare your features complete until someone else has tested it. This can be as simple as walking over to another developer and asking them to try it in front of you. If someone claims a feature is complete, take a few minutes to familiarize yourself with it. If you find a bug, politely mention it to the responsible developer. Slowly build an environment where the team can see the benefits of running tests and tracking features and bugs.
Most teams operate in this manner simply because of a mistaken belief that they don't have time to "do it right", or that they will get to it later. Often this will occur when a simple proof-of-concept done by a developer or two as a side-project turns into a full-on development effort. By showing that it can actually save time and effort, and reducing the initial costs to the rest of the team, you will often find that it becomes ingrained as part of the process without ever actually being officially endorsed or accepted.
If you have management support it will make it much easier, but always be careful to make sure that the team is receptive to the changes. This may mean it takes longer than you want, but so be it, without the team's support any mandated process will fail at the first sign of pressure, which is when you need the process the most.
*Disclaimer - On my last project I spearheaded the movement to tailor the SCRUM process to fit our environment. The "official" process was simply untenable for our client, but it was still an invaluable guide in tailoring our process.
"adding user stories specifically for testing and documenting"
While meta-user stories might make sense in some circles, it rarely works out well. Software folks rarely cope well with meta-user stories, they either don't get the idea that they can change their own processes by writing a story, or -- more typically -- they engineer the meta-user story to death.
When you're interviewing users, it feels like they're making the user story up. Certainly, you're making it up as you listen to them and try to capture it.
When an IT organization tries to make up its own user stories about how IT should work, the process falls apart. Until the organization has done the thing (testing, for example) a bunch of times manually, they're not really qualified to write user stories. Then, after they've done it, they don't need software development processes, they'll just automate the important bits a little at a time.
I think change has to come from a less formal direction. Actually balking at calling something "done" that hasn't been tested is a good starting point.
IT doesn't do things unless forced. So, meet the users and find out why they're not requiring testing. Coach them to require testing. Tell them the consequences and the words to use.
A lot can go wrong in an organization to lead to poor processes. It's important to know what's wrong, and create a demand for change. The best possible thing is to have your boss complaining that you're not fixing it, rather than you suggesting that perhaps it would be good to fix it.
[It doesn't feel right when your boss demands you fix the process, but it's about the only way change will happen.]