Programmer Types:
Do you write extensive design documents for your programs or games?
Is using UML the standard method of diagramming your use cases?
Do you run the whole gamut of diagrams or sort of pick and choose along the way depending on the scope of your software and the number of developers on the team?
First,
If you make documentation, it should have a "clear" reason/purpose.
And this purpose is identify nature of your documentation.
Secondly:
Do not think documentation just in a "written form" or word document.
It may be in any form.Even it can be a "video" in which some guy
explain your major architecture decisons and why they choose
it[motivation]
Well, suppose that you want new team members "easily grab" what you are doing,how you are doing, and why you are doing this way.[ Be carefull all depends on your problem nature]
UML use case diagram may can give overall picture of your functional
requirements. It simply states who will use your system, and what they can
do with your system.
Short memos which state the important non-functional requirements
Short memos which states your major architecture decision and why you give this decisions
Maybe a component diagrams which shows your important components and their interfaces
If application tapology is important then may be a UML deployment diagram which shows how your system will be physically deployed.
But after all you can not document evething and you should not .You can generate whole system UML class diagram automatically with a UML tool, but how can this help a novice.
But you can put class diagrams for classes that do important and tricky
parts and draw sequence diagrams for those tricky parts which show how
they collaborate with other classes while they perform important and
tricky responsibilities.
The key for documentaion is puting yourself into your "audience" [ who
will read your doc] and ask yourself
If I was this document potantial "audience" will i read this document? [ If not why you make doc]
If I read this doc, will it help me in some way? [ it is effective]
Lastly, we do not live in "ideal word"...Sometimes you may find yourself doing doc for no real audience and no real reason just because of some "politics" and you should earn money
Well, in this situation UML will help. Draw boring, with many details [ genarally auotumatically generated] diagrams which no one read or understand but say "Oh you have extensive documentaion". In our software industry, UML is overemphasized, and many guys "buy" even bad doc if there is a UML diagrams in it.
That's all folks...
Related
I want to question and/or perhaps challenge the school of thought on UML behavioral diagrams.
Firstly, I want to ask, what comes first: Use Case or Activity?
I was taught that Use Case diagrams come first and then for each Use Case, you have one or more Activity diagrams to represent successful and alternate flows. From the Activity diagrams, you can identify nouns to establish classes.
I have, however, read other articles which say you create an Activity diagram for the end to end process and then from that, you can identify Use Cases.
I can see both scenarios working, and am confused, as to me it seems a case of hierarchy. For example, say I have a high level business process which is 'Grading Student Results'. If I map it as an Activity diagram, within which I would see swim-lanes. I would be able to pick out Use Cases, such as 'Determine Grade Boundaries,' 'Submit Results,' 'Convert Result to Grade,' and so on.
You could argue they are the same thing, i.e. both diagrams would meet this process modeling need. I then want to model the next level, for example, how you 'Submit Results.'
Can someone advise on the best practice: whether a Use Case diagram comes before or after an Activity diagram?
First:
There is no competition between any of the UML diagrams to be the "first
one". Sometimes it is better to work on some diagrams simultaneously and iteratively.
Second:
Each diagram can be used in different contexts and for different purposes.
Use Case Diagram vs. Activity Diagram
"Use Cases" are scenarios which show how the user will use the system to achieve their goals.
So:
Instead of showing this "scenario" with written use cases, you
can visualize its' steps with an activity diagram.
But in order to find use cases, you should discover the system requirements to some degree, (e.g. the scope, broad feature set, priority, cost, etc.).
In some business domains, such as for an automation project, in order to discover requirements/use cases, you may have to investigate current business flow. Sometimes this business flow can be complex, so you may want to investigate it with an activity diagram.
So:
An activity diagram can be used to investigate a business process to
understand and discover the flow, to better discover requirements.
So:
An Activity Diagram can be used at different levels of software
development stages for different purposes.
Just like other diagrams, you can use the Activity Diagram at any time, anywhere, as soon as it can help you to ask the right question, to understand and explore any issue related to your purpose.
Here is a summary purpose of Activity Diagrams:
The purpose of the activity diagram is to model the procedural flow of
actions that are part of a larger activity. In projects in which use
cases are present, activity diagrams can model a specific use case at
a more detailed level. However, activity diagrams can be used
independently of use cases for modeling a business-level function,
such as buying a concert ticket or registering for a college class.
Activity diagrams can also be used to model system-level functions,
such as how a ticket reservation data-mart populates a corporate
sales system's data warehouse.
UML Basics : The activity diagram by by Donald Bell
To get a quick grasp of which diagrams can be used for which purposes, I advise you to check out Scott W. Ambler's mini book: The Elements of UML(TM) 2.0 Style
Activity diagram is one of the those with widest abstraction range in UML. An activity can be used for anything between a business process (very abstract, comparing with software system) and a single method algorithm (code-level, practically blue-print, meaning kind of abstraction ground level).
Use Cases on the other side are in practice very limited in their abstraction. They show the interaction between a user and the system and would be somewhere in the middle of the abstraction scale. Not as abstract as a business process, and definitelly a lot more abstract than the implementation diagram.
Software projects tend to start working on a very abstract level (business goal for example) and finish with the abstracion 0 (implemented system). During the project analysts, architects and developers work together to gradually lower this abstraction producing always less abstract artifacts/models - business processes, use cases, architecture, design, code.
After this introduction it is not hard to answer your question - any of those can be used first and that depends on type of your project and its size. SOme examples:
A large project of development an ERP system. It is almost certain that in this kind of project the first thing to model is the business process. A long before even thinking of its functionality, the team must understand the business background. The best UML diagram for this is naturally the activity diagram. Some time after, when the process is clear and the high-level reqs known, the use case modelling can start.
A middle sized of relativelly small project, with no complex processes in background (for example a mobile app development) can start directly with use cases, identifying the users and their features. Later on, these can be further refined using activities.
A very small development of some interface, driver of communication gateway, highely technical, where even the user interaction is minimal, the modelling can start with the activities again, showing the concrete algorithm too be implemented. USe cases can be completelly skipped.
As a summary I would conclude that there are no unbreakable rules of this kind in software development. Each project is unique, each development methodology is unique, even each development team is special and unique. To think about "which diagram" to do first is straight and simply WRONG! Think about what kind of analysis or specification you need in a given moment - what is easiest and most usefull to be modelled. When this is clear - there are 13 UML diagrams to pick up from in order to optimally fulfill the aim.
Choice of UML diagram is the "HOW". More important than that is more often than not - the the "WHAT".
Use case diagram is for showing the functionalities and Activity diagram is for showing operations(1 functionality can have many operations).
eg. Use case diag. is Moher (can have many childrens) and
Activity diag. is like describing the child of Mother i.e. Use Case diag.
Can anyone suggest good diagrams/modeling techniques for business process modeling? I was thinking about using activity diagram but the process includes quite a lot of forks and secondly, activity digram may be somewhat difficult to understand to non-technical users.
Sequence diagram is rather similar but what other tools are there? DFD?
For me UML activity or BPMN modelling would be the best way.
Sequence diagram is more appropriate for sequence representation not flow specially with a lot of forks.
There are also the Eriksson-Penker UML extensions. Enterprise Architect from Sparx Systems supports these as well as BPMN; I don't know what sort of support other tools provide.
There are some Topics on Stackoverflow already related on how to model different Threads in UML, for example: Is there an inituitive UML approach to depict threads.
However I still feel, that my case has not been already discussed, even though it should be pretty common:
I am creating an iPhone Application, where I am obviously have a Main-UI-Thread and I am also using Background-Threads to perform Remote-Calls, etc. I basically have 4 different aspects that I like to display within my diagramm:
The UI that is shown to the User.
The Tasks that are being performed by the Main-UI-Thread (therefore blocking the UI)
The Tasks that are performed by Background-Threads
Updates of the UI, which are performed by the UI-Thread, but can be triggered by Background-Threads. For example: new Information loaded from Server, which needs to be displayed on the UI
Has anybody ran into a similiar issue and therefore might show me an example or give me some best practises on how to solve my problem? I am not even sure if I should use a sequence-diagram, an activity-diagram or maybe even some other type.
Well Pascal,
This is not an UML question. It is a design question.
UML just helps you
To understand hard and crtical section of your program/design and to
explore alternative solutions , while writing your code. with the power of visual modeling.
So..
First, ask yourself what kind of parallelism or concurrency exist in
your problem? To investigate this:
Draw a simple activity diagram with partions in which each partions
used to represent different operating system threads or processes.The
object nodes can be used to model the shared objects and data.Forking can be used to model the creation and parallel execution of multiple threads or processes.
Then ask yourself(using that diagram)
What are my shared data? What are my active classes? (threads)What kind of "concurency" problems" may
accour? What may go wrong? What are synronization points? etc..Based on this Explore different alternatives, designs.
The last thing you should worry is UML and its sytax(symbols).
The best UML diagrams are the one that wake up the desire of "asking question" in your mind.
At first forget about Uml. Ask core questions about your problem. If you like visual modeling and your mind like visual thinking use Uml for better understand and investigate possible design solutions.
UML can not design for you...
I found this research papers while searching for same thing
M-UML: an extension to UML for the modeling of mobile
agent-based software systems
May be it can help you
I'm writing an iPhone game and I am trying to write some requirements documents. I have never written requirements before so I got the book Software Requirements. I have not finished it yet, but I forsee some issues, as this book is targeted towards a business. My main question is I am the only person involved with this game and I feel the main purpose of the requirements document should be to nail out as many conceptual ideas of how the game works as I can before I am deep into design or construction. Does anyone have suggestions on how I should lay this out, should I still try to mimic the template provided in the book where it makes sense, or since I am both the sole developer and product owner, should I just stick to game concepts?
You're right that traditional SRS documents don't really fit games documentation all that well. Games instead have a general Game Design Document. It's usually created before any work on the game begins, and it's often edited as the development process goes to keep straight the intended end-result and specifics of the game.
While business software requirements documents are like contracts between a client and developer on what to produce, game design docs are more often specifications from the designer to the artists and programmers on what exactly they need to develop.
There is no specific layout to use. But you should consider who you're writing the document for. Is it for a class, for yourself, for peers after the project is done? The level of detail and the kind of things you include will be different depending on your audience. The format itself is very flexible, as long as it's coherent.
Brenda Brathwaite has a good blog entry on this subject which you might find helpful.
There is a semi-recent article from gamedev.net on the subject as well.
[Poor Jacob, you just read a book on the topic, and, collectively, the SO community writes another one for you, along with extra links, and probably with diverging views ;-) ]
Although I'm not familiar with the book you mention in the question, I think that the following suggestion may help you both take seriously, but also relax a bit, about the all too important question of requirements.
Being a "team of one", it is particularly important, and somewhat paradoxical, that you go through the effort of formalizing the requirements. However, rather than putting too much emphasis on the form, you may find an Agile approach to developement (and hence to requirements gathering) more appropriate. With regards to requirements, one of the main advantages of this approach, is flexibility, i.e. the understanding that while they should be formalized (with limited time/effort), requirements should be allowed to change (within limits) as part of an iterative process towards production of the target product.
In very broad terms, this generally go as follows:
write "user stories", these are individual "cards" (yes, physical cards, say 4 inches by 5 inches, are good, for you can then move then around, sort them etc.)
each story tells a particular feature of the application, here the game, from the end-user's perspective. You can/should start all cards with "As a user, I need the game to..." then follow with a particular feature, for example "... show my high score on the same page as the global high-scores are kept [because ... here optional reasons for why user may want this feature].
review each story and assign a rough estimation of the time involved in implementing it
review each story and assign a priority level (scale may vary, but something simple like "Must have from Version 1.0", "Should eventually be in there, for sure", "Would be nice to have" and "Maybe nice to have...")
organize releases, on the basis of what you can do within say 2 or 3 weeks, maximum. If a particular feature were to take too long, schedule it for a later release.
implement the features assigned to the current release
iterate through this release cycle, reviewing the requirements as you go, for the relative importance of features, and also the need of new features may become evident as with the insight provided by using the [incomplete/imperfect] intermediate releases.
Books like the one you describe are focused at a different audience, but there is value in the general concepts presented. Fully developed requirements documents are not as common as you might think. Don't let anyone think that you are a 'bad developer' for not having the most detailed requirements.
Requirements docs might be more important if you need to communicate the requirements with a co-developer.
If you are the sole developer I would strongly recommend that you spend your efforts on the design and implementation of the game, over requirements. If you have a good idea of what you build then let this flow as you build it.
Documentation can help you. The question is what is going to be most beneficial. Maybe design decisions are more critical than requirements for you but not for others. You'll maybe want to have a list of things that people have requested or ideas that you think of but cannot implement straight away. Sometimes a whiteboard can be handy for sketching out things, it's not just a tool for collaboration with other people.
Here's just a general approach...
Solidify the concept...write it in plain English first (ex: The game is a first person shooter. You kill zombies and hunt for treasure.)
Get a paper pad and pencil and draw out the general flow of the game and the main screens the users will encounter...main menu, options screen, help, etc. Make sure it makes sense.
Go to a site like mockingbird and create the detail wireframes for your screens...
Print these out and do some paper prototyping...i.e. put the printout in front of you and 'click' on a button...then bring up the appropriate screen...then click on another button, etc.
Once that makes sense, you can try to start coding your game.
Personally I believe you should use your own way to do this. The most commonly available one's will not match with your requirement. They might be suitable for a common commercial server application but not for a game. And since iPhone gaming is a new trend you may have to look in a different perspective.. You may not be able to fill a document with standard requirements and you may have different set of New type of requirements.
Just a suggestion... Sign up with Google Sites, and create a private site with documentation of the game, requirements, technical aspects, work log, etc... You can share it with select people, and it always keeps edit history.
I like it better than a Wiki because it is more structured, and just plain simple to use.
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'd like to develop a CMS for fun/personal using asset-based architecture rather than page-based (why, is the purpose of this question), but I can't find much information on the subject. All I've found barely scrapes the surface (there's a good chance I'm searching with the wrong terms).
An asset-based CMS stores information
as blocks of text called assets. These
individual assets are then related to
each other to automatically build
pages.
What are the (dis/)advantages of such a system?
What are the primary principles of asset-based architecture?
What should and shouldn't be an 'asset'? Where can I read more?
Decided to try to answer this after leaving my comment :)
If your definition of "asset" is along the lines of a "node" (such as in Drupal), or a document (such as the JSON-style documents in MongoDB or CouchDB), then here is some info:
I'll use the term "node" for this post. I think it's closest to "asset" and more popularly used. This also might be a very abstract answer, but hopefully it will at least get you thinking and pointed in the right direction.
Node-based architecture, could be described as a cross between neural networking patterns and object-oriented programming. The key is that "nodes" are points of data, and nodes can be connected to each other in some way.
Some architectures will treat nodes much like object-oriented classes, where you have different classes of nodes that can inherit various characteristics of parent nodes - every type of node inherits the basic properties of its parent - an "Essay" node might inherit the properties of a "Text-Document" node, which in turn inherits the properties of the base node. Drupal implements this inheritance model well, although it does not emphasize the connections between nodes in the way that something like Facebook's GraphAPI/Open Graph Protocol does.
This pattern of node-based architecture can be implemented at any level too, and exists in nature - think of social circles within society or ecosystems ;) On a software engineering level, it can take the form of a database, such as how MongoDB simply has nodes of data (which are called documents in that case). These documents can reference other documents, although, like Drupal, Mongo does not emphasize connectedness. Ironically, relational databases like MySQL that are the opposite of document-based databases actually emphasize connectedness more, but that's a discussion for another day. Facebook's GraphAPI that I mentioned above is implemented on a Web-API level. The Open Graph Protocol shapes it. And again, something like Drupal is implemented at the front-end level (although its back-end implements the node pattern on a lower level, of course).
Lastly, node-based architecture is much more flexible than traditional document/page based CMS architecture, but that also means there is a lot more programming and configuring to be done on the side of the developers. A node-based system will end up being far more inter-connected and its components will be integrated with one-another a deeper level, but it can also be more susceptible to breaking because of this deep level of connection - it is less than separated into individual modules. Personally, I see a huge trend where people are moving to become more "node-based" and less "content-based" as people begin to interact with websites more like applications than as electronic magazines as they did in the 90's. Plus, the node-pattern fits well with the increasing emphasis on user-contribution and social browsing because adding people and their accounts/profiles to a web site dramatically increases the complexity.
I know you said "asset," so I'll also say that asset emphasizes the data side of the node pattern more, whereas "node" emphasizes the connections between the pieces of data more.
But for further reading, I'd recommend reading up on the architecture of the software I mentioned. You could also check out node.js, JSON, and document-based databases, and GraphAPI's as they seem to fit well with this idea of asset/node-based architecture. I'm sure Wikipedia has some good stuff on these patterns as well.
You could very quickly scale this up using the CakePHP framework. It uses an MVC pattern and it provides classes called elements that may be inserted into layouts and can load whatever content you want based on the page, user, moon phase, etc.
<page>
<element calls methodX>
<element calls methodY>
<Default Content relies on Controller Action(view/edit/add/custom)>
<element calls methodZ>
</page>
I think you might be describing a CMS backed up by a content repository.
The repository itself is implemented by Apache Jackrabbit based on JSR 170:
The API should be a standard, implementation independent, way to access content bi-directionally on a granular level within a content repository. A Content Repository is a high-level information management system that is a superset of traditional data repositories. A content repository implements "content services" such as: author based versioning, full textual searching, fine grained access control, content categorization and content event monitoring. It is these "content services" that differentiate a Content Repository from a Data Repository.
For a CMS working on top a content repository, look at Nuxeo.